Clientes

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

Criação de um cliente

POSThttps://api-cwb.cldware.com/customers

Body

data*object

Response

Body

dataobject

Request

const response = await fetch('https://api-cwb.cldware.com/customers', {
    method: 'POST',
    headers: {
      "Content-Type": "application/json"
    },
    body: JSON.stringify({
      "data": {
        "type": "customers",
        "attributes": {
          "business_name": "Nome do cliente"
        }
      }
    }),
});
const data = await response.json();

Response

{
  "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"
        }
      }
    }
  }
}

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>

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 um cliente

PATCHhttps://api-cwb.cldware.com/customers/{id}

Path parameters

id*string

Body

data*object

Response

Request

const response = await fetch('https://api-cwb.cldware.com/customers/{id}', {
    method: 'PATCH',
    headers: {
      "Content-Type": "application/json"
    },
    body: JSON.stringify({
      "data": {
        "type": "customers",
        "id": "1",
        "attributes": {}
      }
    }),
});
const data = await response.json();

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

GEThttps://api-cwb.cldware.com/customers/{id}

Path parameters

id*string

Response

Body

dataobject

Request

const response = await fetch('https://api-cwb.cldware.com/customers/{id}', {
    method: 'GET',
    headers: {},
});
const data = await response.json();

Response

{
  "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"
        }
      }
    }
  }
}

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>'

Eliminação de um cliente

DELETEhttps://api-cwb.cldware.com/customers/{id}

Path parameters

id*string

Response

Request

const response = await fetch('https://api-cwb.cldware.com/customers/{id}', {
    method: 'DELETE',
    headers: {},
});
const data = await response.json();

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>'

PreviousIntrodução à API v0 NextFornecedores

Last updated 3 months ago