Documentação API
  • Introdução
  • Setup
  • Autenticação
  • Autenticação ( Authorization Code Flow )
  • Caraterísticas dos pedidos
  • API-v1
    • Introdução à API v1
    • Documentos de venda
    • Notas de venda
    • Notas de liquidação de venda
    • Recibos
    • Documentos de compra
    • Notas de compra
    • Notas de liquidação de compra
    • Pagamentos
    • Documentos e notas de venda no regime de Balcão Único do IVA (OSS)
  • API-v0
    • Introdução à API v0
    • Clientes
    • Fornecedores
    • Contactos
    • Moradas
    • Produtos e serviços
    • Documentos de venda
    • Recibos
    • Descarregar PDF de documentos e recibos
    • Envio de documentos e recibos por email
    • Documentos de compra
    • Pagamentos
    • Anexar ficheiros
    • Comunicação de documentos à AT
    • Contabilização
Powered by GitBook
On this page
  1. API-v0

Clientes

As rotas aqui descritas permitem criar, modificar e remover clientes.

PreviousIntrodução à API v0NextFornecedores

Last updated 11 months ago

Criação de um cliente

curl -v -X POST -H 'Content-Type: application/vnd.api+json' -H 'Accept: application/json' -H 'Authorization: Bearer <access_token>' -d '<payload JSON>' '<API_URL>/customers'

No pedido acima, o access_token é o token de acesso válido devolvido pelo serviço de OAuth. O payload JSON a enviar contém a seguinte informação:

{
  "data": {
    "type": "customers",                                          // [OBRIGATÓRIO]
    "attributes": {                                               // [OBRIGATÓRIO] Os atributos do cliente
      "tax_registration_number": "999999990",                     // [OPCIONAL] Por omissão, "999999990". Se o país for Portugal, deve ser um NIF português válido.
      "business_name": "Nome do cliente",                         // [OBRIGATÓRIO]
      "contact_name": "Nome do contacto",                         // [OPCIONAL]
      "website": "www.test.pt",                                   // [OPCIONAL] Site web
      "phone_number": "2212312312",                               // [OPCIONAL] Número de telefone
      "mobile_number": "9612312312",                              // [OPCIONAL] Número de telemóvel
      "email": "test@tests.pt",                                   // [OPCIONAL] Endereço de email principal
      "country_iso_alpha_2": "PT",                                // [OPCIONAL] País do cliente. Por omissão, "PT"; é o código ISO alpha-2 do país do cliente (vd. https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2; ver também a NOTA 1.
      "not_final_customer": false,                                // [OPCIONAL] Por omissão, false; true se o cliente for um sujeito passivo.
      "is_tax_exempt": false,                                     // [OPCIONAL] Por omissão, false; true se o cliente estiver isento de IVA.
      "cashed_vat": false,                                        // [OPCIONAL] Por omissão, false; true se o cliente estiver no regime de IVA de caixa.
      "observations": "Observações ao cliente",                   // [OPCIONAL]
      "internal_observations": "Observações internas ao cliente"  // [OPCIONAL]
    },
    "relationships": {                                            // [OPCIONAL] Recursos associados ao cliente. Caso nenhum seja indicado, este bloco "relationships" deve ser omitido
      // Motivo de isenção de IVA. [OBRIGATÓRIO] apenas se o cliente estiver isento de IVA. Não deve ser indicado nos restantes casos.
      "tax_exemption_reason": {
        "data": {
          "type": "tax_exemption_reasons",                        // [OBRIGATÓRIO]
          "id": "1"                                               // [OBRIGATÓRIO] Identificador interno do motivo de isenção do IVA. Ver NOTA 2.
        }
      }
    }
  }
}
  • NOTA 1: São também suportados dois "países" adicionais: "PT-AC" (Portugal, Açores) e "PT-MA" (Portugal, Madeira). Os países disponíveis podem ser consultados por um GET /countries, ou um em particular por um

GET /countries?filter[iso_alpha_2]=PT|<o código do país>
  • NOTA 2: O "id" interno do motivo de isenção deve ser obtido por um

GET /tax_exemption_reasons?filter[code]=M07|<o código legal do motivo de isenção>  

Alteração de um cliente

curl -v -X PATCH -H 'Content-Type: application/vnd.api+json' -H 'Accept: application/json' -H 'Authorization: Bearer <access_token>' -d '<payload JSON>' '<API_URL>/customers/<id do cliente>'

No pedido acima, o access_token é o token de acesso válido devolvido pelo serviço de OAuth e o id do cliente é o "id" interno do cliente, devolvido no campo "id" da resposta ao seu pedido de criação (ver Criação de um cliente). O payload JSON a enviar contém a seguinte informação:

{
  "data": {
    "type": "customers",                                          // [OBRIGATÓRIO]
    "id": "1",                                                    // [OBRIGATÓRIO] O identificador interno do cliente. Este "id" é o devolvido na resposta ao pedido de criação do cliente, ver acima.
    "attributes": {                                               // [OBRIGATÓRIO] Os atributos do cliente
      "tax_registration_number": "999999990",                     // [OPCIONAL] Se o país for Portugal, deve ser um NIF português válido.
      "business_name": "Nome do cliente",                         // [OPCIONAL]
      "contact_name": "Nome do contacto",                         // [OPCIONAL]
      "website": "www.test.pt",                                   // [OPCIONAL] Site web
      "phone_number": "2212312312",                               // [OPCIONAL] Número de telefone
      "mobile_number": "9612312312",                              // [OPCIONAL] Número de telemóvel
      "email": "test@tests.pt",                                   // [OPCIONAL] Endereço de email principal
      "country_iso_alpha_2": "PT",                                // [OPCIONAL] País do cliente; é o código ISO alpha-2 do país do cliente (vd. https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2; ver também a NOTA 1.
      "not_final_customer": false,                                // [OPCIONAL] true se o cliente for um sujeito passivo.
      "is_tax_exempt": false,                                     // [OPCIONAL] true se o cliente estiver isento de IVA.
      "cashed_vat": false,                                        // [OPCIONAL] true se o cliente estiver no regime de IVA de caixa.
      "observations": "Observações ao cliente",                   // [OPCIONAL]
      "internal_observations": "Observações internas ao cliente"  // [OPCIONAL]
    },
    "relationships": {                                            // [OPCIONAL] Recursos associados ao cliente. Caso nenhum seja indicado, este bloco "relationships" deve ser omitido
      // Motivo de isenção de IVA. [OBRIGATÓRIO] apenas se o cliente estiver isento de IVA. Não deve ser indicado nos restantes casos.
      "tax_exemption_reason": {
        "data": {
          "type": "tax_exemption_reasons",                        // [OBRIGATÓRIO]
          "id": "1"                                               // [OBRIGATÓRIO] Identificador interno do motivo de isenção do IVA. Ver NOTA 2.
        }
      }
    }
  }
}

Todos os atributos são opcionais: apenas devem ser enviados os atributos que se deseja alterar, não indicando os que se mantêm inalterados.

  • NOTA 1: São também suportados dois "países" adicionais: "PT-AC" (Portugal, Açores) e "PT-MA" (Portugal, Madeira). Os países disponíveis podem ser consultados por um GET /countries, ou um em particular por um

GET /countries?filter[iso_alpha_2]=PT|<o código do país>
  • NOTA 2: O "id" interno do motivo de isenção deve ser obtido por um

GET /tax_exemption_reasons?filter[code]=M07|<o código legal do motivo de isenção>  

Consulta de um cliente

curl -v -X GET -H 'Content-Type: application/vnd.api+json' -H 'Accept: application/json' -H 'Authorization: Bearer <access_token>' '<API_URL>/customers/<id do cliente>'

No pedido acima, o access_token é o token de acesso válido devolvido pelo serviço de OAuth e o id do cliente é o "id" interno do cliente, devolvido no campo "id" da resposta ao seu pedido de criação (ver Criação de um cliente).

Eliminação de um cliente

curl -v -X DELETE -H 'Content-Type: application/vnd.api+json' -H 'Accept: application/json' -H 'Authorization: Bearer <access_token>' '<API_URL>/customers/<id do cliente>'

No pedido acima, o access_token é o token de acesso válido devolvido pelo serviço de OAuth e o id do cliente é o "id" interno do cliente, devolvido no campo "id" da resposta ao seu pedido de criação (ver Criação de um cliente).

Ao ser criado o cliente, é também criada automaticamente uma morada a ele associada: a morada principal (sede), que pode ser alterada como se descreve em .

Alteração de uma morada
get
Path parameters
idstringRequired
Responses
200
OK
application/json
get
GET /customers/{id} HTTP/1.1
Host: api-cwb.cldware.com
Accept: */*
200

OK

{
  "data": {
    "type": "customers",
    "id": "1",
    "attributes": {
      "tax_registration_number": 999999990,
      "business_name": "Nome do cliente",
      "contact_name": "Nome do contacto",
      "website": "www.test.pt",
      "phone_number": 2212312312,
      "mobile_number": 9612312312,
      "email": "test@tests.pt",
      "country_iso_alpha_2": "PT",
      "not_final_customer": false,
      "is_tax_exempt": false,
      "cashed_vat": false,
      "observations": "Observações ao cliente",
      "internal_observations": "Observações internas ao cliente"
    },
    "relationships": {
      "main_address": {
        "data": {
          "type": "addresses",
          "id": "1"
        }
      },
      "addresses": {
        "data": [
          {
            "type": "addresses",
            "id": "1"
          }
        ]
      },
      "main_email_address": {
        "data": {
          "type": "email_addresses",
          "id": "1"
        }
      },
      "email_addresses": {
        "data": [
          {
            "type": "email_addresses",
            "id": "1"
          }
        ]
      },
      "tax_exemption_reason": {
        "data": {
          "type": "tax_exemption_reasons",
          "id": "1"
        }
      },
      "defaults": {
        "data": {
          "type": "customer_defaults",
          "id": "1"
        }
      }
    }
  }
}
delete
Path parameters
idstringRequired
Responses
200
OK
delete
DELETE /customers/{id} HTTP/1.1
Host: api-cwb.cldware.com
Accept: */*
200

OK

No content

  • Criação de um cliente
  • POST/customers
  • Alteração de um cliente
  • PATCH/customers/{id}
  • Consulta de um cliente
  • GET/customers/{id}
  • Eliminação de um cliente
  • DELETE/customers/{id}
post
Body
Responses
200
OK
application/json
post
POST /customers HTTP/1.1
Host: api-cwb.cldware.com
Content-Type: application/json
Accept: */*
Content-Length: 538

{
  "data": {
    "type": "customers",
    "attributes": {
      "tax_registration_number": 999999990,
      "business_name": "Nome do cliente",
      "contact_name": "Nome do contacto",
      "website": "www.test.pt",
      "phone_number": 2212312312,
      "mobile_number": 9612312312,
      "email": "test@tests.pt",
      "country_iso_alpha_2": "PT",
      "not_final_customer": false,
      "is_tax_exempt": false,
      "cashed_vat": false,
      "observations": "Observações ao cliente",
      "internal_observations": "Observações internas ao cliente"
    },
    "relationships": {
      "tax_exemption_reason": {
        "data": {
          "type": "tax_exemption_reasons",
          "id": "1"
        }
      }
    }
  }
}
200

OK

{
  "data": {
    "type": "customers",
    "id": "1",
    "attributes": {
      "tax_registration_number": 999999990,
      "business_name": "Nome do cliente",
      "contact_name": "Nome do contacto",
      "website": "www.test.pt",
      "phone_number": 2212312312,
      "mobile_number": 9612312312,
      "email": "test@tests.pt",
      "country_iso_alpha_2": "PT",
      "not_final_customer": false,
      "is_tax_exempt": false,
      "cashed_vat": false,
      "observations": "Observações ao cliente",
      "internal_observations": "Observações internas ao cliente"
    },
    "relationships": {
      "main_address": {
        "data": {
          "type": "addresses",
          "id": "1"
        }
      },
      "addresses": {
        "data": [
          {
            "type": "addresses",
            "id": "1"
          }
        ]
      },
      "main_email_address": {
        "data": {
          "type": "email_addresses",
          "id": "1"
        }
      },
      "email_addresses": {
        "data": [
          {
            "type": "email_addresses",
            "id": "1"
          }
        ]
      },
      "tax_exemption_reason": {
        "data": {
          "type": "tax_exemption_reasons",
          "id": "1"
        }
      },
      "defaults": {
        "data": {
          "type": "customer_defaults",
          "id": "1"
        }
      }
    }
  }
}
patch
Path parameters
idstringRequired
Body
Responses
200
OK
patch
PATCH /customers/{id} HTTP/1.1
Host: api-cwb.cldware.com
Content-Type: application/json
Accept: */*
Content-Length: 547

{
  "data": {
    "type": "customers",
    "id": "1",
    "attributes": {
      "tax_registration_number": 999999990,
      "business_name": "Nome do cliente",
      "contact_name": "Nome do contacto",
      "website": "www.test.pt",
      "phone_number": 2212312312,
      "mobile_number": 9612312312,
      "email": "test@tests.pt",
      "country_iso_alpha_2": "PT",
      "not_final_customer": false,
      "is_tax_exempt": false,
      "cashed_vat": false,
      "observations": "Observações ao cliente",
      "internal_observations": "Observações internas ao cliente"
    },
    "relationships": {
      "tax_exemption_reason": {
        "data": {
          "type": "tax_exemption_reasons",
          "id": "1"
        }
      }
    }
  }
}
200

OK

No content