Fornecedores

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

Criação de um fornecedor

post

Body

Responses

200

OK

application/json

post/suppliers

POST /suppliers HTTP/1.1
Host: api-cwb.cldware.com
Content-Type: application/json
Accept: */*
Content-Length: 385

{
  "data": {
    "type": "suppliers",
    "attributes": {
      "tax_registration_number": 999999990,
      "business_name": "Nome do fornecedor",
      "website": "www.test.pt",
      "country_iso_alpha_2": "PT",
      "is_taxable": false,
      "is_tax_exempt": false,
      "self_billing": false,
      "internal_observations": "Observações internas ao fornecedor"
    },
    "relationships": {
      "tax_exemption_reason": {
        "data": {
          "type": "tax_exemption_reasons",
          "id": "1"
        }
      }
    }
  }
}

200

OK

{
  "data": {
    "type": "suppliers",
    "id": "1",
    "attributes": {
      "tax_registration_number": 999999990,
      "business_name": "Nome do fornecedor",
      "website": "www.test.pt",
      "country_iso_alpha_2": "PT",
      "is_taxable": false,
      "is_tax_exempt": false,
      "self_billing": false,
      "internal_observations": "Observações internas ao fornecedor"
    },
    "relationships": {
      "main_address": {
        "data": {
          "type": "addresses",
          "id": "1"
        }
      },
      "addresses": {
        "data": [
          {
            "type": "addresses",
            "id": "1"
          }
        ]
      },
      "main_contact": {
        "data": {
          "type": "contacts",
          "id": "1"
        }
      },
      "contacts": {
        "data": [
          {
            "type": "contacts",
            "id": "1"
          }
        ]
      },
      "tax_exemption_reason": {
        "data": {
          "type": "tax_exemption_reasons",
          "id": "1"
        }
      },
      "defaults": {
        "data": {
          "type": "supplier_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>/suppliers'

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": "suppliers",                                            // [OBRIGATÓRIO]
    "attributes": {                                                 // [OBRIGATÓRIO] Os atributos do fornecedor
      "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 fornecedor",                        // [OBRIGATÓRIO]
      "website": "www.test.pt",                                     // [OPCIONAL] Site web
      "country_iso_alpha_2": "PT",                                  // [OPCIONAL] País do fornecedor. Por omissão, "PT"; é o código ISO alpha-2 do país do fornecedor (vd. https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2; ver também a NOTA 1.
      "is_taxable": false,                                          // [OPCIONAL] Por omissão, false; true se o fornecedor for um sujeito passivo.
      "is_tax_exempt": false,                                       // [OPCIONAL] Por omissão, false; true se o fornecedor estiver isento de IVA.
      "self_billing": false,                                        // [OPCIONAL] Por omissão, false; true se o fornecedor estiver disponível para auto-faturação.
      "internal_observations": "Observações internas ao fornecedor" // [OPCIONAL]
    },
    "relationships": {                                              // [OPCIONAL] Recursos associados ao fornecedor. Caso nenhum seja indicado, este bloco "relationships" deve ser omitido
      // Motivo de isenção de IVA. [OBRIGATÓRIO] apenas se o fornecedor 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 fornecedor, é 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 fornecedor

patch

Path parameters

idstringRequired

Body

Responses

200

OK

No content

patch/suppliers/{id}

PATCH /suppliers/{id} HTTP/1.1
Host: api-cwb.cldware.com
Content-Type: application/json
Accept: */*
Content-Length: 394

{
  "data": {
    "type": "suppliers",
    "id": "1",
    "attributes": {
      "tax_registration_number": 999999990,
      "business_name": "Nome do fornecedor",
      "website": "www.test.pt",
      "country_iso_alpha_2": "PT",
      "is_taxable": false,
      "is_tax_exempt": false,
      "self_billing": false,
      "internal_observations": "Observações internas ao fornecedor"
    },
    "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>/suppliers/<id do fornecedor>'

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

{
  "data": {
    "type": "suppliers",                                            // [OBRIGATÓRIO]
    "id": "1",                                                      // [OBRIGATÓRIO] O identificador interno do fornecedor. Este "id" é o devolvido na resposta ao pedido de criação do fornecedor, ver acima.
    "attributes": {                                                 // [OBRIGATÓRIO] Os atributos do fornecedor
      "tax_registration_number": "999999990",                       // [OPCIONAL] Se o país for Portugal, deve ser um NIF português válido.
      "business_name": "Nome do fornecedor",                        // [OPCIONAL]
      "website": "www.test.pt",                                     // [OPCIONAL] Site web
      "country_iso_alpha_2": "PT",                                  // [OPCIONAL] País do fornecedor; é o código ISO alpha-2 do país do fornecedor (vd. https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2; ver também a NOTA 1.
      "is_taxable": false,                                          // [OPCIONAL] true se o fornecedor for um sujeito passivo.
      "is_tax_exempt": false,                                       // [OPCIONAL] true se o fornecedor estiver isento de IVA.
      "self_billing": false,                                        // [OPCIONAL] true se o fornecedor estiver disponível para auto-faturação.
      "internal_observations": "Observações internas ao fornecedor" // [OPCIONAL]
    },
    "relationships": {                                              // [OPCIONAL] Recursos associados ao fornecedor. Caso nenhum seja indicado, este bloco "relationships" deve ser omitido
      // Motivo de isenção de IVA. [OBRIGATÓRIO] apenas se o fornecedor 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 fornecedor

get

Path parameters

idstringRequired

Responses

200

OK

application/json

get/suppliers/{id}

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

200

OK

{
  "data": {
    "type": "suppliers",
    "id": "1",
    "attributes": {
      "tax_registration_number": 999999990,
      "business_name": "Nome do fornecedor",
      "website": "www.test.pt",
      "country_iso_alpha_2": "PT",
      "is_taxable": false,
      "is_tax_exempt": false,
      "self_billing": false,
      "internal_observations": "Observações internas ao fornecedor"
    },
    "relationships": {
      "main_address": {
        "data": {
          "type": "addresses",
          "id": "1"
        }
      },
      "addresses": {
        "data": [
          {
            "type": "addresses",
            "id": "1"
          }
        ]
      },
      "main_contact": {
        "data": {
          "type": "contacts",
          "id": "1"
        }
      },
      "contacts": {
        "data": [
          {
            "type": "contacts",
            "id": "1"
          }
        ]
      },
      "tax_exemption_reason": {
        "data": {
          "type": "tax_exemption_reasons",
          "id": "1"
        }
      },
      "defaults": {
        "data": {
          "type": "supplier_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>/suppliers/<id do fornecedor>'

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

Eliminação de um fornecedor

delete

Path parameters

idstringRequired

Responses

200

OK

No content

delete/suppliers/{id}

DELETE /suppliers/{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>/suppliers/<id do fornecedor>'

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