### Instalar e usar o SDK PHP da Facturalusa

Source: https://facturalusa.pt/documentacao/api/sdks-e-plugins

Instala o SDK PHP da Facturalusa via Composer, cria um cliente com um token de API, cria um cliente de venda e imprime a resposta. O token 'api_token' deve ser substituído pelo token real.

```bash
// Instalação
$ composer require infolusa/php-facturalusa
```

```php
// Utilização
$facturalusa = new \Facturalusa\FacturalusaClient('api_token');
$customer = new \Facturalusa\SaleCustomer\SaleCustomer($facturalusa);
$customer->create([]);
```

```php
// Resposta
print_r($facturalusa->response());
```

--------------------------------

### Resposta exemplo - Assinar digitalmente recibo

Source: https://facturalusa.pt/documentacao/api/recibos/assinar-digitalmente

Resposta de sucesso da operação de assinatura digital. Devolve um objeto com a propriedade `url_file` que contém o URL do documento assinado.

```json
{ url_file }
```

--------------------------------

### Resposta exemplo - Clientes - Procurar (JSON)

Source: https://facturalusa.pt/documentacao/api/clientes/procurar

Exemplo de resposta da API para a operação de procurar um cliente. Devolve um objeto com os campos do cliente, todos com valor null exceto irs_retention_tax que é "0.00". Use para validar a estrutura esperada da resposta.

```json
{
    "id": null,
    "code": null,
    "name": null,
    "vat_number": null,
    "country": null,
    "address": null,
    "city": null,
    "postal_code": null,
    "email": null,
    "telephone": null,
    "mobile": null,
    "currency_id": null,
    "payment_method_id": null,
    "payment_condition_id": null,
    "shipping_mode_id": null,
    "price_id": null,
    "employee_id": null,
    "type": null,
    "vat_exemption_id": null,
    "vat_type": null,
    "irs_retention_tax": "0.00",
    "observations": null,
    "other_contacts": null,
    "other_emails": null,
    "code_blocked": null,
    "vat_number_blocked": null,
    "name_blocked": null,
    "receive_sms": null,
    "receive_emails": null,
    "language": null,
    "active": null,
    "updated_at": null,
    "created_at": null
}
```

--------------------------------

### POST /sales

Source: https://facturalusa.pt/documentacao/api/vendas/criar

Cria um novo documento de venda (Factura, Orçamento, Encomenda, Guia, etc.). Este endpoint já disponibiliza o URL para download do documento gerado, sendo desnecessária a posterior chamada do endpoint `sales/:id/download`.

```APIDOC
## POST /sales

### Description
Cria um novo documento de venda (Factura, Orçamento, Encomenda, Guia, etc.). Este endpoint já disponibiliza o URL para download do documento gerado, sendo desnecessária a posterior chamada do endpoint `sales/:id/download`.

### Method
POST

### Endpoint
/sales

### Parameters
#### Request Body
- **sale_reference_id** (integer) - Opcional - ID da venda a ser referenciada. Apenas deve ser preenchido quando o documento a ser emitido se trata de uma Nota de crédito ou Nota de débito e há uma referência a uma Factura, Factura Simplificada ou Factura Recibo.
- **issue_date** (date) - Obrigatório - Data de emissão do documento
- **due_date** (date) - Opcional - Data de vencimento do documento
- **document_type** (mixed) - Obrigatório - Tipo de documento. Pode ser enviado o ID ou o descritivo, exemplo: `Factura`, `Factura Recibo`, `Factura Simplificada`, `Nota de Crédito`, `Nota de Débito`, `Factura Pró-forma`, `Orçamento`, `Encomenda`, `Consulta de Mesa`, `Caução`, `Guia de Transporte`, `Guia de Remessa`, `Guia de Consignação`, `Guia de Devolução`, `Guia de movimentação de activos próprios`.
- **serie** (mixed) - Opcional - Série. Pode ser enviado o ID ou o descritivo, exemplo: `2021`, `2021A`, etc. No caso de não preenchimento será assumido a série pré-definida.
- **final_discount_financial** (double) - Opcional - Desconto financeiro €
- **final_discount_global** (double) - Opcional - Desconto global %
- **customer** (mixed) - Obrigatório - ID ou código do cliente
- **vat_number** (string) - Opcional - Contribuinte do cliente. No caso de não preenchimento será assumido o valor `999999990`.
- **address** (string) - Opcional - Morada do cliente. No caso de não preenchimento será assumido o valor `Desconhecido`.
- **city** (string) - Opcional - Localidade do cliente. No caso de não preenchimento será assumido o valor `Desconhecido`.
- **postal_code** (string) - Opcional - Código postal do cliente. No caso de não preenchimento será assumido o valor `Desconhecido`.
- **country** (string) - Opcional - País do cliente. No caso de não preenchimento será assumido o valor `Portugal`.
- **delivery_address_address** (string) - Opcional - Morada de entrega
- **delivery_address_city** (string) - Opcional - Localidade da morada de entrega
- **delivery_address_postal_code** (string) - Opcional - Código postal da morada de entrega
- **delivery_address_country** (string) - Opcional - País da morada de entrega
- **payment_method** (mixed) - Opcional - Forma de pagamento. Pode ser enviado o ID ou o descritivo, exemplo: `Numerário`, `Transferência bancária`, etc.
- **payment_condition** (mixed) - Opcional - Condição de pagamento. Pode ser enviado o ID ou o descritivo, exemplo: `Pronto pagamento`, `30 dias`, etc.
- **shipping_mode** (mixed) - Opcional - Modo de expedição. Pode ser enviado o ID ou o descritivo, exemplo: `Correios`, `Comboio`, etc.
- **shipping_value** (double) - Opcional - Custo unitário da despesa de transporte
- **shipping_vat** (mixed) - Opcional - Taxa de IVA da despesa de transporte. Pode ser enviado o ID, descritivo ou a taxa, exemplo: `23`, `13`, etc.
- **price** (mixed) - Opcional - Tabela de preços utilizada. Pode ser enviado o ID ou o descritivo, exemplo: `Preços público`, `Preços revenda`, etc. No caso de não preenchimento será assumido a tabela de preços pré-definida.
- **currency** (mixed) - Opcional - Moeda utilizada. Pode ser enviado o ID, símbolo ou descritivo, exemplo: `€`, `$`, `Euro`, `Dólar`. No caso de não preenchimento será assumido a moeda pré-definida.
- **currency_exchange** (double) - Opcional - Câmbio da moeda. Caso não seja enviado será assumido `1`.
- **vat_type** (string) - Obrigatório - Tipo de IVA. Deve ser enviado um dos seguintes valores: `Debitar IVA`, `IVA incluído`, `Não fazer nada`.
- **observations** (string) - Opcional - Observações do documento
- **external_reference** (string) - Opcional - Identificador único do documento numa plataforma externa, utilizado para garantir a idempotência das operações. Se já existir uma venda com a mesma referência, será devolvida a venda existente em vez de ser criada uma nova.
- **irs_retention_tax** (double) - Opcional - Taxa de retenção na fonte
- **vehicle** (mixed) - Opcional - Veículo utilizado. Este campo apenas deve ser utilizado quando o tipo de documento emitido se trata de uma guia. Pode ser enviado o ID, matrícula ou nome.
- **employee** (mixed) - Opcional - Vendedor do documento. Pode ser enviado o ID ou o email.
- **waybill_shipping_date** (datetime) - Obrigatório se waybill - Data de início de transporte da guia.
- **waybill_global** (boolean) - Opcional - Indica se a guia é global.

### Request Example
```json
{
  "issue_date": "2023-01-01",
  "document_type": "Factura",
  "customer": "123",
  "vat_type": "Debitar IVA"
}
```

### Response
#### Success Response (200)
- **id** (integer) - ID da venda criada
- **url** (string) - URL para download do documento gerado

#### Response Example
```json
{
  "id": 1,
  "url": "https://example.com/download/1"
}
```
```

--------------------------------

### POST /api/v2/sales/:id/download

Source: https://facturalusa.pt/documentacao/api/vendas/download

Permite efectuar download de um documento de venda no estado Terminado ou Cancelado.

```APIDOC
## POST /api/v2/sales/:id/download

### Description
Permite efectuar download de um documento no estado `Terminado` ou `Cancelado`.

### Method
POST

### Endpoint
https://facturalusa.pt/api/v2/sales/:id/download

### Parameters
#### Query Parameters
- **language** (string) - Optional - Idioma a ser impresso. Preencher com `PT` ou `EN`. No caso de não preenchimento será assumido o idioma previamente guardado.
- **format** (string) - Optional - Formato a ser impresso caso o estado do documento seja `Terminado`. Preencher com `A4`, `POS` ou `EscPOS`. No caso de não preenchimento será assumido o valor definido no tipo de documento (que por norma é A4). Os formatos `A4` e `POS` produzem um ficheiro PDF. O formato `EscPOS` produz um ficheiro TXT com os comandos da impressora em `Base64`.
- **paper_size** (integer) - Optional - Tamanho / largura do documento em milímetros. Apenas deve ser preenchido caso o formato seja `POS` ou `EscPOS`. No caso de não preenchimento será assumido o valor definido no tipo de documento.
- **paper_left_margin** (integer) - Optional - Margem à esquerda do documento. No caso de não preenchimento será assumido o valor definido no tipo de documento.
- **paper_right_margin** (integer) - Optional - Margem à direita do documento. No caso de não preenchimento será assumido o valor definido no tipo de documento.
- **paper_top_margin** (integer) - Optional - Margem em cima do documento. No caso de não preenchimento será assumido o valor definido no tipo de documento.
- **paper_bottom_margin** (integer) - Optional - Margem em baixo do documento. No caso de não preenchimento será assumido o valor definido no tipo de documento.
- **issue** (string) - Optional - Via a imprimir. Preencher com `2ª via` ou `Original`. No caso de não preenchimento será assumido `2ª via`.
- **max_items_per_page** (integer, max 25) - Optional - Nº de artigos a imprimir por página. No caso de não preenchimento será assumido o valor pré-definido.

### Response
#### Success Response (200)
- **url** (string) - URL do documento para download.

#### Response Example
```
{ url }
```

```

--------------------------------

### Resposta exemplo da API - Atualizar forma de pagamento

Source: https://facturalusa.pt/documentacao/api/administracao-formas-pagamento/actualizar

Exemplo de resposta da API para o pedido de atualização de uma forma de pagamento. O objeto contém os campos id, description e description_english, que são devolvidos com valores nulos no exemplo.

```json
{
    "id": null,
    "description": null,
    "description_english": null
}
```

--------------------------------

### POST /api/v2/administration/currencies

Source: https://facturalusa.pt/documentacao/api/administracao-moedas/criar

Cria uma nova moeda na administração. A moeda é sempre criada no estado 'activo'.

```APIDOC
## [POST] /api/v2/administration/currencies

### Description
Cria uma nova moeda na administração. A moeda é sempre criada no estado `activo`.

### Method
POST

### Endpoint
https://facturalusa.pt/api/v2/administration/currencies

### Parameters
#### Request Body
- **description** (string) - Required - Descrição
- **symbol** (string) - Required - Símbolo
- **code_iso** (string) - Required - Código ISO
- **exchange_sale** (double) - Required - Câmbio de venda
- **is_default** (boolean) - Optional - Pré-definido

### Response
#### Success Response (201)

#### Response Example
```
{
    "id": null,
    "description": null,
    "symbol": null
}
```
```

--------------------------------

### POST /api/v2/sales/summary

Source: https://facturalusa.pt/documentacao/api/vendas/sumario

Calcula os totais de um documento de venda em tempo real. Envia os dados do documento e recebe os valores calculados como resposta.

```APIDOC
## POST /api/v2/sales/summary

### Description
Calcula em tempo real os totais (total de IVA, total geral, etc) que vão ser emitidos no documento de venda.

### Method
POST

### Endpoint
https://facturalusa.pt/api/v2/sales/summary

### Parameters
#### Request Body
- **document_type** (mixed) - Required - Tipo de documento. Pode ser enviado o ID ou o descritivo, exemplo: `Factura`, `Factura Recibo`, `Factura Simplificada`, `Nota de Crédito`, `Nota de Débito`, `Factura Pró-forma`, `Orçamento`, `Encomenda`, `Consulta de Mesa`, `Guia de Transporte`, `Guia de Remessa`, `Guia de Consignação`, `Guia de Devolução`, `Guia de movimentação de ativos próprios`.
- **final_discount_financial** (double) optional - Desconto financeiro €
- **final_discount_global** (double) optional - Desconto global %
- **shipping_mode** (mixed) optional - Modo de expedição. Pode ser enviado o ID ou o descritivo, exemplo: `Correios`, `Comboio`, etc.
- **shipping_value** (double) optional - Custo unitário da despesa de transporte
- **shipping_vat** (mixed) optional - Taxa de IVA da despesa de transporte. Pode ser enviado o ID, descritivo ou a taxa, exemplo: `23`, `13`, etc.
- **currency** (mixed) optional - Moeda utilizada. Pode ser enviado o ID, símbolo ou descritivo, exemplo: `€`, `$`, `Euro`, `Dólar`. No caso de não preenchimento será assumido a moeda pré-definida.
- **currency_exchange** (double) optional - Câmbio da moeda. Caso não seja enviado será assumido `1`.
- **vat_type** (string) required - Tipo de IVA. Deve ser enviado um dos seguintes valores: `Debitar IVA`, `IVA incluído`, `Não fazer nada`.
- **irs_retention_tax** (double) optional - Taxa de retenção na fonte
- **items** (json array) required - Lista de artigos que constam no documento.
  - **id** (mixed) required - ID ou referência do artigo
  - **details** (string) optional - Descrição adicional a aparecer no documento (máx. 255 caracteres)
  - **price** (double) required - Preço unitário
  - **quantity** (double) required - Quantidade
  - **discount** (double) optional - Desconto percentual
  - **vat** (mixed) required - Taxa de IVA a aplicar. Pode ser enviado o ID, descritivo ou a taxa, exemplo: `23`, `13`, etc.
  - **vat_exemption** (mixed) optional - Isenção de IVA a aplicar. Pode ser enviado o ID ou o código, exemplo: `M08`, etc. No caso de não preenchimento será assumido o valor `M18 - Sem isenção`.

### Response
#### Success Response (200)
- **gross_total** (string) - Total bruto
- **total_discount** (string) - Total de descontos
- **net_total** (string) - Total líquido
- **total_base_vat** (string) - Total base de IVA
- **total_vat** (string) - Total de IVA
- **total_shipping** (string) - Total de transporte
- **grand_total** (string) - Total geral
- **grand_total_with_currency_exchange** (string) - Total geral com câmbio
- **final_discount_financial** (string) - Desconto financeiro
- **final_discount_global** (string) - Desconto global percentual
- **final_discount_global_value** (string) - Valor do desconto global
- **total_services** (string) - Total de serviços
- **total_quantity** (string) - Quantidade total
- **irs_retention_apply** (boolean) - Indica se retenção de IRS é aplicada
- **irs_retention_base** (string) - Base de retenção de IRS
- **irs_retention_total** (string) - Total de retenção de IRS
- **irs_retention_tax** (string) - Taxa de retenção de IRS
- **items** (array) - Lista de itens
- **vats** (array) - Lista de taxas de IVA

#### Response Example
```json
{
    "gross_total": "0.00",
    "total_discount": "0.00",
    "net_total": "0.00",
    "total_base_vat": "0.00",
    "total_vat": "0.00",
    "total_shipping": "0.00",
    "grand_total": "0.00",
    "grand_total_with_currency_exchange": "0.00",
    "final_discount_financial": "0.00",
    "final_discount_global": "0.00",
    "final_discount_global_value": "0.00",
    "total_services": "0.00",
    "total_quantity": "0.00",
    "irs_retention_apply": false,
    "irs_retention_base": "0.00",
    "irs_retention_total": "0.00",
    "irs_retention_tax": "0.00",
    "items": [],
    "vats": []
}
```
```

--------------------------------

### Exemplo de pedido autenticado com Bearer Token

Source: https://facturalusa.pt/documentacao/api/autenticacao

Exemplo de pedido autenticado com Bearer Token. Substitua API_KEY pela sua chave de API. O endpoint é apenas ilustrativo.

```bash
curl --request POST
--url 'https://facturalusa.pt/api/v2/sample'
--header "Authorization: Bearer API_KEY"
--header 'Accept: application/json'
--header 'Content-type: application/json'
--body '{"param1": "value1"}'
```

--------------------------------

### Resposta exemplo - Gerar referência multibanco

Source: https://facturalusa.pt/documentacao/api/vendas/gerar-referencia-multibanco

Exemplo de resposta da API ao gerar uma referência multibanco para uma venda. Contém os campos entity, sub_entity e reference.

```json
{
    entity: 000,
    sub_entity: 000,
    reference: 000000000
}
```

--------------------------------

### Exemplo de resposta da API (JSON)

Source: https://facturalusa.pt/documentacao/api/administracao-condicoes-pagamento/actualizar

Resposta de exemplo retornada pelo endpoint de atualização. Inclui os campos atualizados da condição de pagamento.

```json
{
    "id": null,
    "description": null,
    "description_english": null,
    "days": null
}
```

--------------------------------

### PUT /api/v2/sales/:id/generate_mbref

Source: https://facturalusa.pt/documentacao/api/vendas/gerar-referencia-multibanco

Gera uma referência multibanco para um documento de venda. Apenas pode ser utilizado caso o documento se encontre no estado `Terminado` e nos seguintes tipos de documento: `Factura`, `Factura Pró-forma`, `Encomenda` e `Orçamento`.

```APIDOC
## PUT /api/v2/sales/:id/generate_mbref

### Description
Gera uma referência multibanco para um documento de venda. Apenas pode ser utilizado caso o documento se encontre no estado `Terminado` e nos seguintes tipos de documento: `Factura`, `Factura Pró-forma`, `Encomenda` e `Orçamento`.

### Method
PUT

### Endpoint
https://facturalusa.pt/api/v2/sales/:id/generate_mbref

### Parameters
#### Path Parameters
- **id** (string) - Required - Identificador do documento de venda.

### Response
#### Success Response (200)
- **entity** (number) - Entidade da referência multibanco.
- **sub_entity** (number) - Sub-entidade da referência multibanco.
- **reference** (number) - Referência multibanco gerada.

#### Response Example
```
{
    entity: 000,
    sub_entity: 000,
    reference: 000000000
}
```

### Error Handling
Possíveis erros:
- Não existe nenhuma configuração de referências de multibanco
- Não é possível gerar a referência MB no tipo de documento seleccionado
- O documento já possui uma referência de multibanco
```

--------------------------------

### Resposta exemplo da API - Procurar artigo

Source: https://facturalusa.pt/documentacao/api/artigos/procurar

Exemplo de resposta da API para a operação de procurar um artigo. A resposta contém campos como id, reference, description, entre outros, com valores nulos ou vazios, e um array prices vazio. Deve ser testada e validada numa plataforma de testes de API como Postman ou Insomnia.

```json
{
    "id": null,
    "reference": null,
    "description": null,
    "details": null,
    "details_show_print": null,
    "type": null,
    "cost_price": "0.00000",
    "observations": null,
    "reference_blocked": null,
    "description_blocked": null,
    "active": null,
    "updated_at": null,
    "created_at": null,
    "prices": []
}
```

--------------------------------

### POST /api/v2/administration/locations

Source: https://facturalusa.pt/documentacao/api/administracao-locais/criar

Cria um novo local na administração. O local é sempre criado no estado 'activo'. É necessário fornecer os campos obrigatórios como nome, morada, cidade, código postal, país, tipo de local, tipo de documento e tipo de IVA.

```APIDOC
## [POST] /api/v2/administration/locations

### Description
Cria um novo local na administração. O local é sempre criado no estado `activo`.

### Method
POST

### Endpoint
https://facturalusa.pt/api/v2/administration/locations

### Parameters
#### Request Body
- **name** (string) - Required - Nome
- **address** (string) - Required - Morada
- **city** (string) - Required - Localidade
- **postal_code** (string) - Required - Código postal
- **country** (string) - Required - País
- **telephone** (string) - Optional - Telefone
- **type** (string) - Required - Tipo de local. Preencher com `Interno` ou `Externo`.
- **document_type** (string) - Required - Tipo de documento. Pode ser enviado o ID ou o descritivo, exemplo: `Factura`, `Factura Recibo`, `Factura Simplificada`, `Nota de crédito` ou `Nota de débito`
- **vat_type** (string) - Required - Tipo de IVA. Deve ser enviado um dos seguintes valores: `Debitar IVA`, `IVA incluído`, `Não fazer nada`.
- **warehouse** (string) - Optional - Armazém. Pode ser enviado o ID ou o descritivo.

### Response
#### Success Response (201)
- **id** (string) - Identificador do local criado (pode ser null)
- **name** (string) - Nome do local criado (pode ser null)

#### Response Example
```
{
    "id": null,
    "name": null
}
```
```

--------------------------------

### POST https://facturalusa.pt/api/v2/administration/prices

Source: https://facturalusa.pt/documentacao/api/administracao-tabela-precos/criar

Creates a new price table. The price table is always created in the `activo` state.

```APIDOC
## [POST] https://facturalusa.pt/api/v2/administration/prices

### Description
Creates a new price table. The price table is always created in the `activo` state.

### Method
POST

### Endpoint
https://facturalusa.pt/api/v2/administration/prices

### Parameters
#### Request Body
- **description** (string) - Required - Description
- **is_default** (boolean) - Optional - Pré-definido

### Request Example
{
  "description": "string",
  "is_default": true
}

### Response
#### Success Response (201)
- **id** (null) - Description
- **description** (null) - Description

#### Response Example
{
  "id": null,
  "description": null
}
```

--------------------------------

### POST /api/v2/customers

Source: https://facturalusa.pt/documentacao/api/clientes/criar

Cria um novo cliente na Facturalusa. O cliente é sempre criado no estado activo. Este endpoint aceita um corpo de pedido com os dados do cliente e devolve o cliente criado com o código de resposta 201.

```APIDOC
## POST /api/v2/customers

### Description
Cria um novo cliente na Facturalusa. O cliente é sempre criado no estado `activo`.

### Method
POST

### Endpoint
https://facturalusa.pt/api/v2/customers

### Parameters
#### Request Body
- **code** (string) - Optional - Código do cliente. Se não for enviado nenhum valor vai ser dado seguimento ao último código ou gerado um código aleatório.
- **name** (string) - Required - Nome
- **vat_number** (string) - Optional - Contribuinte
- **country** (string) - Optional - País
- **address** (string) - Optional - Morada
- **city** (string) - Optional - Localidade
- **postal_code** (string) - Optional - Código postal
- **email** (string) - Optional - Email
- **telephone** (string) - Optional - Telefone
- **mobile** (string) - Optional - Telemóvel. Evite espaços e +351.
- **currency** (mixed) - Optional - Moeda utilizada. Pode ser enviado o ID, símbolo ou descritivo, exemplo: `€`, `$`, `Euro`, `Dólar`. No caso de não preenchimento será assumido a moeda pré-definida.
- **payment_method** (mixed) - Optional - Forma de pagamento. Pode ser enviado o ID ou o descritivo, exemplo: `Numerário`, `Transferência bancária`, etc.
- **payment_condition** (mixed) - Optional - Condição de pagamento. Pode ser enviado o ID ou o descritivo, exemplo: `Pronto pagamento`, `30 dias`, etc.
- **shipping_mode** (mixed) - Optional - Modo de expedição. Pode ser enviado o ID ou o descritivo, exemplo: `Correios`, `Comboio`, etc.
- **price** (mixed) - Optional - Tabela de preços utilizada. Pode ser enviado o ID ou o descritivo, exemplo: `Preços público`, `Preços revenda`, etc.
- **employee** (mixed) - Optional - Vendedor que adquiriu o cliente. Pode ser enviado o ID ou o email.
- **type** (string) - Required - Tipo de cliente. Deve ser enviado um dos seguintes valores: `Empresarial`, `Particular`.
- **vat_type** (string) - Required - Tipo de IVA. Deve ser enviado um dos seguintes valores: `Debitar IVA`, `IVA incluído`, `Não fazer nada`.
- **vat_exemption** (mixed) - Optional - Isenção de IVA a aplicar. Pode ser enviado o ID ou o código, exemplo: `M08`, etc. No caso de não preenchimento será assumido o valor `M18 - Sem isenção`.
- **irs_retention_tax** (double) - Optional - Taxa de retenção na fonte
- **observations** (string) - Optional - Observações do cliente
- **other_contacts** (string) - Optional - Outros contactos
- **other_emails** (string) - Optional - Outros emails. Emails separados por vírgula.
- **receive_sms** (boolean) - Optional - Determina se o cliente está apto a receber notificações de SMS despoletadas automaticamente
- **receive_emails** (boolean) - Optional - Determina se o cliente está apto a receber notificações de Emails despoletadas automaticamente
- **language** (string) - Optional - Determina o idioma por defeito no cliente. Deve ser enviado um dos seguintes valores: `Auto`, `PT`, `EN`. No caso de não preenchimento será assumido `Auto`.
- **addresses** (json array) - Optional - Lista de moradas de entrega.
  - **country** (string) - Optional - País
  - **address** (string) - Optional - Morada
  - **city** (string) - Optional - Localidade
  - **postal_code** (string) - Optional - Código postal

### Response
#### Success Response (201)
- **id** (null) - Identificador do cliente
- **code** (null) - Código do cliente
- **name** (null) - Nome
- **vat_number** (null) - Contribuinte
- **country** (null) - País
- **address** (null) - Morada
- **city** (null) - Localidade
- **postal_code** (null) - Código postal
- **email** (null) - Email
- **telephone** (null) - Telefone
- **mobile** (null) - Telemóvel
- **currency_id** (null) - ID da moeda
- **payment_method_id** (null) - ID da forma de pagamento
- **payment_condition_id** (null) - ID da condição de pagamento
- **shipping_mode_id** (null) - ID do modo de expedição
- **price_id** (null) - ID da tabela de preços
- **employee_id** (null) - ID do vendedor
- **type** (null) - Tipo de cliente
- **vat_exemption_id** (null) - ID da isenção de IVA
- **vat_type** (null) - Tipo de IVA
- **irs_retention_tax** (string) - Taxa de retenção na fonte
- **observations** (null) - Observações
- **other_contacts** (null) - Outros contactos
- **other_emails** (null) - Outros emails
- **code_blocked** (null) - Indica se o código está bloqueado
- **vat_number_blocked** (null) - Indica se o contribuinte está bloqueado
- **name_blocked** (null) - Indica se o nome está bloqueado
- **receive_sms** (null) - Indica se recebe SMS
- **receive_emails** (null) - Indica se recebe emails
- **language** (null) - Idioma
- **active** (null) - Estado ativo
- **updated_at** (null) - Data de atualização
- **created_at** (null) - Data de criação

#### Response Example
```json
{
    "id": null,
    "code": null,
    "name": null,
    "vat_number": null,
    "country": null,
    "address": null,
    "city": null,
    "postal_code": null,
    "email": null,
    "telephone": null,
    "mobile": null,
    "currency_id": null,
    "payment_method_id": null,
    "payment_condition_id": null,
    "shipping_mode_id": null,
    "price_id": null,
    "employee_id": null,
    "type": null,
    "vat_exemption_id": null,
    "vat_type": null,
    "irs_retention_tax": "0.00",
    "observations": null,
    "other_contacts": null,
    "other_emails": null,
    "code_blocked": null,
    "vat_number_blocked": null,
    "name_blocked": null,
    "receive_sms": null,
    "receive_emails": null,
    "language": null,
    "active": null,
    "updated_at": null,
    "created_at": null
}
```
```

--------------------------------

### POST /api/v2/administration/paymentmethods

Source: https://facturalusa.pt/documentacao/api/administracao-formas-pagamento/criar

Cria uma nova forma de pagamento. A forma de pagamento é sempre criada no estado 'activo'. O campo 'description' é obrigatório e 'description_english' é opcional.

```APIDOC
## POST /api/v2/administration/paymentmethods

### Description
Cria uma nova forma de pagamento. A forma de pagamento é sempre criada no estado `activo`.

### Method
POST

### Endpoint
https://facturalusa.pt/api/v2/administration/paymentmethods

### Parameters
#### Request Body
- **description** (string) - Required - Descrição
- **description_english** (string) - Optional - Descrição em inglês. No caso de não preenchimento será assumido o valor do campo `description`.

### Request Example
{
  "description": "string",
  "description_english": "string"
}

### Response
#### Success Response (201)
- **id** (null) - Identificador da forma de pagamento criada
- **description** (null) - Descrição
- **description_english** (null) - Descrição em inglês

#### Response Example
{
  "id": null,
  "description": null,
  "description_english": null
}
```

--------------------------------

### Exemplo de resposta da API (JSON)

Source: https://facturalusa.pt/documentacao/api/administracao-colaboradores/procurar

Exemplo de resposta retornada pelo endpoint de procura. Contém os campos 'id' e 'name', ambos com valor null no exemplo.

```json
{
    "id": null,
    "name": null
}
```

--------------------------------

### Resposta exemplo do sumário de recibos

Source: https://facturalusa.pt/documentacao/api/recibos/sumario

Exemplo de resposta da API para o sumário de recibos. Devolve os totais calculados (desconto, saldo, pago, total geral e total com câmbio) e a lista de vendas. Pode ser validado em plataformas como Postman ou Insomnia.

```json
{
    "total_discount": "0.00",
    "total_balance": "0.00",
    "total_paid": "0.00",
    "grand_total": "0.00",
    "grand_total_with_currency_exchange": "0.00",
    "sales": []
}
```

--------------------------------

### Resposta exemplo do endpoint de sumário

Source: https://facturalusa.pt/documentacao/api/vendas/sumario

Exemplo da estrutura de resposta JSON retornada pelo endpoint de sumário com os totais calculados.

```json
{
    "gross_total": "0.00",
    "total_discount": "0.00",
    "net_total": "0.00",
    "total_base_vat": "0.00",
    "total_vat": "0.00",
    "total_shipping": "0.00",
    "grand_total": "0.00",
    "grand_total_with_currency_exchange": "0.00",
    "final_discount_financial": "0.00",
    "final_discount_global": "0.00",
    "final_discount_global_value": "0.00",
    "total_services": "0.00",
    "total_quantity": "0.00",
    "irs_retention_apply": false,
    "irs_retention_base": "0.00",
    "irs_retention_total": "0.00",
    "irs_retention_tax": "0.00",
    "items": [],
    "vats": []
}
```

--------------------------------

### POST /receipts

Source: https://facturalusa.pt/documentacao/api/recibos/criar

Cria um novo recibo e devolve o URL para download do documento gerado.

```APIDOC
## POST /receipts

### Description
Cria um novo recibo e devolve o URL para download do documento gerado.

### Method
POST

### Endpoint
/receipts

### Parameters
#### Request Body
- **issue_date** (date) - Required - Data de emissão do documento
- **receipt_date** (date) - Required - Data de recebimento do documento
- **document_type** (mixed) - Required - Tipo de documento. Pode ser enviado o ID ou o descritivo, exemplo: `Recibo de Cliente`.
- **serie** (mixed) - Optional - Série. Pode ser enviado o ID ou o descritivo, exemplo: `2021`, `2021A`, etc. No caso de não preenchimento será assumido a série pré-definida.
- **customer** (mixed) - Required - ID ou código do cliente
- **vat_number** (string) - Optional - Contribuinte do cliente. No caso de não preenchimento será assumido o valor `999999990`.
- **address** (string) - Required - Morada do cliente
- **city** (string) - Required - Localidade do cliente
- **postal_code** (string) - Required - Código postal do cliente
- **country** (string) - Required - País do cliente
- **payment_method** (mixed) - Optional - Forma de pagamento. Pode ser enviado o ID ou o descritivo, exemplo: `Numerário`, `Transferência bancária`, etc.
- **currency** (mixed) - Optional - Moeda utilizada. Pode ser enviado o ID, símbolo ou descritivo, exemplo: `€`, `$`, `Euro`, `Dólar`. No caso de não preenchimento será assumido a moeda pré-definida.
- **currency_exchange** (double) - Optional - Câmbio da moeda. Caso não seja enviado será assumido `1`.
- **observations** (string) - Optional - Observações do documento
- **external_reference** (string) - Optional - Identificador único do documento numa plataforma externa, utilizado para garantir a idempotência das operações. Se já existir um recibo com a mesma referência, será devolvida o recibo existente em vez de ser criado um novo.
- **location_origin** (mixed) - Optional - Local de origem. Pode ser enviado o ID ou nome do local. No caso de não preenchimento será assumido o local de origem pré-definido.
- **sales** (json array) - Required - Lista de vendas que constam no documento.
  - **id** (integer) - Required - ID da venda
  - **deposit_id** (integer) - Optional - ID da caução. Identifica o documento de caução previamente emitido e indica que esta factura foi liquidada (total ou parcialmente) com esse valor.
  - **discount** (double) - Optional - Desconto a aplicar
  - **discount_type** (string) - Optional - Tipo de desconto a aplicar. Pode ser enviado `Percentagem` ou `Unitário`.
  - **total_paid** (double) - Required - Valor pago
- **language** (string) - Optional - Idioma a ser impresso caso o estado do documento seja `Terminado`. Preencher com `PT` ou `EN`. No caso de não preenchimento será assumido o idioma pré-definido.
- **format** (string) - Optional - Formato a ser impresso caso o estado do documento seja `Terminado`. Preencher com `A4` ou `POS`. No caso de não preenchimento será assumido o valor definido no tipo de documento (que por norma é A4).
- **paper_size** (integer) - Optional - Tamanho / largura do documento em milímetros. Apenas deve ser preenchido caso o formato seja `POS`. No caso de não preenchimento será assumido o valor definido no tipo de documento.
- **paper_left_margin** (integer) - Optional - Margem à esquerda do documento. No caso de não preenchimento será assumido o valor definido no tipo de documento.
- **paper_right_margin** (integer) - Optional - Margem à direita do documento. No caso de não preenchimento será assumido o valor definido no tipo de documento.
- **paper_top_margin** (integer) - Optional - Margem em cima do documento. No caso de não preenchimento será assumido o valor definido no tipo de documento.
- **paper_bottom_margin** (integer) - Optional - Margem em baixo do documento. No caso de não preenchimento será assumido o valor definido no tipo de documento.
- **force_print** (boolean) - Optional - Determina se deve ou não gerar a impressão do documento caso o estado do mesmo seja `Terminado`. Se preenchido com `true` o documento será impresso; se preenchido com `false` o documento não será impresso; se não for preenchido, irá assumir o valor definido no tipo de documento.
- **force_send_email** (boolean) - Optional - Determina se deve ou não enviar via email o documento para o cliente caso o estado do mesmo seja `Terminado`. Se preenchido com `true` o documento será enviado; se preenchido com `false` o documento não será enviado; se não for preenchido, irá assumir o valor definido no tipo de documento.
- **force_send_sms** (boolean) - Optional - Determina se deve ou não enviar SMS para o cliente caso o estado do documento seja `Terminado`. Se preenchido com `true` a SMS será enviada; se preenchido com `false` a SMS não será enviada; se não for preenchido, irá assumir o valor definido no tipo de documento. Esta funcionalidade só funciona se tiver SMS disponíveis.
- **force_sign** (boolean) - Optional - Determina se deve ou não assinar o documento (não descrito no texto, mas presente como campo).

### Request Example
```json
{
  "issue_date": "2023-01-01",
  "receipt_date": "2023-01-01",
  "document_type": "Recibo de Cliente",
  "customer": 1,
  "address": "Rua Exemplo, 123",
  "city": "Lisboa",
  "postal_code": "1000-000",
  "country": "Portugal",
  "sales": [
    {
      "id": 1,
      "total_paid": 100.00
    }
  ]
}
```

### Response
#### Success Response (200)
- **url** (string) - URL para download do documento gerado (não explicitamente descrito, mas mencionado que o endpoint já disponibiliza o URL).

#### Response Example
```json
{
  "url": "https://example.com/download/recibo.pdf"
}
```
```

--------------------------------

### POST /api/v2/administration/shippingmodes

Source: https://facturalusa.pt/documentacao/api/administracao-modos-expedi%C3%A7%C3%A3o/criar

Cria um novo modo de expedição. O modo é criado no estado 'activo'. O campo 'description' é obrigatório e 'description_english' é opcional, assumindo o valor de 'description' se não preenchido.

```APIDOC
## POST /api/v2/administration/shippingmodes

### Description
Cria um novo modo de expedição. O modo é criado no estado `activo`.

### Method
POST

### Endpoint
https://facturalusa.pt/api/v2/administration/shippingmodes

### Parameters
#### Request Body
- **description** (string) - Required - Descrição
- **description_english** (string) - Optional - Descrição em inglês. No caso de não preenchimento será assumido o valor do campo `description`.

### Request Example
{
  "description": "string",
  "description_english": "string"
}

### Response
#### Success Response (201)
- **id** (integer) - ID do modo de expedição criado
- **description** (string) - Descrição
- **description_english** (string) - Descrição em inglês

#### Response Example
{
  "id": null,
  "description": null,
  "description_english": null
}
```

--------------------------------

### Exemplo de resposta da API para procurar categoria

Source: https://facturalusa.pt/documentacao/api/administracao-categorias/procurar

Resposta de exemplo em formato JSON com os campos 'id' e 'description', ambos com valor null. Sugere-se testar a resposta completa em ferramentas como Postman ou Insomnia.

```json
{
    "id": null,
    "description": null
}
```