Clientes

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

Criação de um cliente

post

Body

application/json

Responses

200

OK

application/json

post

/customers

HTTPcURLJavaScriptPython

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": "[e-mail]",
      "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": "[e-mail]",
      "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"
        }
      }
    }
  }
}

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": "[e-mail]",                                   // [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>  

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.

Alteração de um cliente

patch

Path parameters

idstringRequired

Body

application/json

Responses

200

OK

No content

patch

/customers/{id}

HTTPcURLJavaScriptPython

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": "[e-mail]",
      "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

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": "[e-mail]",                                   // [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

get

Path parameters

idstringRequired

Responses

200

OK

application/json

get

/customers/{id}

HTTPcURLJavaScriptPython

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": "[e-mail]",
      "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"
        }
      }
    }
  }
}

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

delete

Path parameters

idstringRequired

Responses

200

OK

No content

delete

/customers/{id}

HTTPcURLJavaScriptPython

DELETE /customers/{id} HTTP/1.1
Host: api-cwb.cldware.com
Accept: */*

200

OK

No content

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).