Fornecedores

As rotas definidas no presente capítulo permitem gerir toda a informação relativa a fornecedores: criação, edição, remoção, etc

Esta primeira rota permite obter a informação de todos os fornecedores disponíveis. Para tal, deve apenas realizar o seguinte pedido:

get

Responses

200

OK

application/json

get/suppliers

GET /suppliers HTTP/1.1
Accept: */*

200

OK

{
  "data": {
    "type": "suppliers",
    "id": null,
    "attributes": {
      "id": 1,
      "tax_registration_number": "text",
      "business_name": "text",
      "website": "text",
      "is_taxable": true,
      "is_tax_exempt": true,
      "self_billing": true,
      "document_series_id": 1,
      "internal_observations": "text",
      "tax_country_region": "text",
      "is_independent_worker": true,
      "country_iso_alpha_2": "text",
      "saft_import_id": 1
    },
    "relationships": {
      "company": {
        "data": {
          "resource": "current_company"
        }
      },
      "main_address": {
        "data": {
          "table": "addresses",
          "resource": "addresses"
        }
      },
      "main_contact": {
        "data": {
          "table": "contacts",
          "resource": "contacts"
        }
      },
      "tax_exemption_reason": {
        "data": {
          "resource": "tax_exemption_reasons"
        }
      },
      "addresses": {
        "data": {
          "table": "addresses",
          "resource": "addresses"
        }
      },
      "contacts": {
        "data": {
          "table": "contacts",
          "resource": "contacts"
        }
      },
      "bank_accounts": {
        "data": {
          "table": "bank_accounts",
          "resource": "bank_accounts"
        }
      }
    }
  }
}

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

Por outro lado, se pretender obter a informação de um fornecedor específico, deverá realizar o mesmo pedido, especificando o id do fornecedor que deseja consultar

get

Path parameters

idintegerRequired

Responses

200

OK

No content

get/suppliers/{id}

GET /suppliers/{id} HTTP/1.1
Accept: */*

200

OK

No content

curl -v -X POST -H 'Content-Type: application/vnd.api+json' -H 'Accept: application/json' -H 'Authorization: Bearer <access_token>' '<API_URL>/suppliers'/{id}

A seguinte rota permite a criação de novas instâncias de fornecedores. De modo a realizar um pedido para esta rota, terá de enviar alguns parâmetros no body do pedido. Tal como está descrito no pedido em baixo, dentro do body terá de criar dois objetos: data, e relationships. Dentro de data, deverá colocar todos os parâmetros obrigatórios (assinalados com um asterisco), e poderá também colocar os restantes parâmetros, se for do seu interesse. O tipo dos parâmetros está também especificado. Dentro de relationships deverá colocar um objeto para cada uma das entradas descritas em baixo, sendo que cada uma deverá conter todos os parâmetros indicados.

post

Body

Responses

200

OK

application/json

post/suppliers

POST /suppliers HTTP/1.1
Content-Type: application/json
Accept: */*
Content-Length: 822

{
  "data": {
    "type": "suppliers",
    "attributes": {
      "id": 1,
      "tax_registration_number": "text",
      "business_name": "text",
      "website": "text",
      "is_taxable": true,
      "is_tax_exempt": true,
      "self_billing": true,
      "document_series_id": 1,
      "internal_observations": "text",
      "tax_country_region": "text",
      "is_independent_worker": true,
      "country_iso_alpha_2": "text",
      "saft_import_id": 1
    },
    "relationships": {
      "company": {
        "data": {
          "resource": "current_company"
        }
      },
      "main_address": {
        "data": {
          "table": "addresses",
          "resource": "addresses"
        }
      },
      "main_contact": {
        "data": {
          "table": "contacts",
          "resource": "contacts"
        }
      },
      "tax_exemption_reason": {
        "data": {
          "resource": "tax_exemption_reasons"
        }
      },
      "addresses": {
        "data": {
          "table": "addresses",
          "resource": "addresses"
        }
      },
      "contacts": {
        "data": {
          "table": "contacts",
          "resource": "contacts"
        }
      },
      "bank_accounts": {
        "data": {
          "table": "bank_accounts",
          "resource": "bank_accounts"
        }
      }
    }
  }
}

200

OK

{
  "data": {
    "type": "suppliers",
    "id": null,
    "attributes": {
      "id": 1,
      "tax_registration_number": "text",
      "business_name": "text",
      "website": "text",
      "is_taxable": true,
      "is_tax_exempt": true,
      "self_billing": true,
      "document_series_id": 1,
      "internal_observations": "text",
      "tax_country_region": "text",
      "is_independent_worker": true,
      "country_iso_alpha_2": "text",
      "saft_import_id": 1
    },
    "relationships": {
      "company": {
        "data": {
          "resource": "current_company"
        }
      },
      "main_address": {
        "data": {
          "table": "addresses",
          "resource": "addresses"
        }
      },
      "main_contact": {
        "data": {
          "table": "contacts",
          "resource": "contacts"
        }
      },
      "tax_exemption_reason": {
        "data": {
          "resource": "tax_exemption_reasons"
        }
      },
      "addresses": {
        "data": {
          "table": "addresses",
          "resource": "addresses"
        }
      },
      "contacts": {
        "data": {
          "table": "contacts",
          "resource": "contacts"
        }
      },
      "bank_accounts": {
        "data": {
          "table": "bank_accounts",
          "resource": "bank_accounts"
        }
      }
    }
  }
}

Em alternativa, temos descrito o cURL necessário para realizar este pedido:

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'

Neste, o payload JSON deverá ser do seguinte formato

{
    "data": {
        "type": "suppliers",
        "attributes": {
            "tax_registration_number": null,
            "business_name": null,
            "website": null,
            "is_taxable": null,
            "is_tax_exempt": null,
            "self_billing": null,
            "document_series_id": null,
            "internal_observations": null,
            "tax_country_region": null,
            "is_independent_worker": null
        },
        "relationships": {
            "main_address": {
                "data": {
                    "type": "addresses",
                    "id": 1
                }
            },
            "main_contact": {
                "data": {
                    "type": "contacts",
                    "id": 1
                }
            },
            "addresses": {
                "data": [
                    {
                        "type": "addresses",
                        "id": 1
                    },
                    {
                        "type": "addresses",
                        "id": 2
                    }
                ]
            },
            "contacts": {
                "data": [
                    {
                        "type": "contacts",
                        "id": 1
                    },
                    {
                        "type": "contacts",
                        "id": 2
                    }
                ]
            }
        }
    }
}

A seguinte rota permite a remoção de um dado fornecedor. Esta rota deve ser utilizada de forma cautelosa dado que é irreversível, e mesmo que este cliente volte a ser criado, o seu id nunca será o mesmo que teria anteriormente. Utilizando o id do forncedor que quer eliminar, que poderá fazer utilizando a primeira rota desta página, por exemplo, terá simplesmente de fazer o pedido:

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

Este irá retornar OK em caso de sucesso.

delete

Path parameters

idintegerRequired

Responses

200

OK

No content

delete/suppliers/{id}

DELETE /suppliers/{id} HTTP/1.1
Accept: */*

200

OK

No content

A rota PATCH permite a edição de um fornecedor existente. O body deste pedido deverá ser igual ao descrito na rota POST, contendo todas as informações obrigatórias do fornecedor, atualizadas para os valores que tenciona alterar, além do "id" do fornecedor. Álem disto, o pedido deverá ser feito a https://apiv1.toconline.com/suppliers/{id}, sendo que {id} é o identificador do fornecedor que tenciona atualizar.

patch

Path parameters

idintegerRequired

Responses

200

OK

No content

patch/suppliers/{id}

PATCH /suppliers/{id} HTTP/1.1
Accept: */*

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

Neste, o PAYLOAD_JSON deverá ser do seguinte formato:

{
    "data": {
        "type": "suppliers",
        "id": "1",
        "attributes": {
            "tax_registration_number": null,
            "business_name": null,
            "website": null,
            "is_taxable": null,
            "is_tax_exempt": null,
            "self_billing": null,
            "document_series_id": null,
            "internal_observations": null,
            "tax_country_region": null,
            "is_independent_worker": null
        },
        "relationships": {
            "main_address": {
                "data": {
                    "type": "addresses",
                    "id": 1
                }
            },
            "main_contact": {
                "data": {
                    "type": "contacts",
                    "id": 1
                }
            },
            "addresses": {
                "data": [
                    {
                        "type": "addresses",
                        "id": 1
                    },
                    {
                        "type": "addresses",
                        "id": 2
                    }
                ]
            },
            "contacts": {
                "data": [
                    {
                        "type": "contacts",
                        "id": 1
                    },
                    {
                        "type": "contacts",
                        "id": 2
                    }
                ]
            }
        }
    }
}

Morada

De modo a associar uma morada a um cliente, deverá realizar o seguinte pedido

patch

Body

Responses

200

OK

application/json

patch/addresses

PATCH /addresses HTTP/1.1
Content-Type: application/json
Accept: */*
Content-Length: 541

{
  "data": {
    "type": "addresses",
    "attributes": {
      "id": 1,
      "is_primary": true,
      "address_detail": "text",
      "city": "text",
      "postcode": "text",
      "region": "text",
      "name": "text",
      "for_discharge": true,
      "for_charge": true
    },
    "relationships": {
      "country": {
        "data": {
          "resource": "countries"
        }
      },
      "company": {
        "data": {
          "table": "addresses",
          "resource": "current_company"
        }
      },
      "customer": {
        "data": {
          "table": "addresses",
          "resource": "customers"
        }
      },
      "supplier": {
        "data": {
          "table": "addresses",
          "resource": "suppliers"
        }
      },
      "user": {
        "data": {
          "table": "addresses",
          "resource": "current_company_users"
        }
      }
    },
    "id": "text"
  }
}

200

OK

{
  "data": {
    "type": "addresses",
    "id": null,
    "attributes": {
      "id": 1,
      "is_primary": true,
      "address_detail": "text",
      "city": "text",
      "postcode": "text",
      "region": "text",
      "name": "text",
      "for_discharge": true,
      "for_charge": true
    },
    "relationships": {
      "country": {
        "data": {
          "resource": "countries"
        }
      },
      "company": {
        "data": {
          "table": "addresses",
          "resource": "current_company"
        }
      },
      "customer": {
        "data": {
          "table": "addresses",
          "resource": "customers"
        }
      },
      "supplier": {
        "data": {
          "table": "addresses",
          "resource": "suppliers"
        }
      },
      "user": {
        "data": {
          "table": "addresses",
          "resource": "current_company_users"
        }
      }
    }
  }
}

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

No pedido acima, o <access_token> corresponde ao token de acesso válido devolvido pelo serviço de OAuth, e o <payload JSON> deverá ter o seguinte formato

// Exemplo de payload

{
  "data": {
    "type": "addresses",                              // [OBRIGATÓRIO]
    "id": "<id da morada principal do cliente>",      // [OBRIGATÓRIO]
    "attributes": {
      "address_detail": "Test address",               // [OPCIONAL]
      "city": "Test city",                            // [OPCIONAL]
      "postcode": "0000-000",                         // [OPCIONAL] Se o país for Portugal, deve obedecer ao formato português, DDDD-DDD
      "region": "Test region"                         // [OPCIONAL]
    },
    "relationships": {                                // [OPCIONAL] Recursos associados à morada. Caso nenhum seja indicado, este bloco "relationships" deve ser omitido
      "country": {                                    // [OPCIONAL] Por omissão, a morada fica associada ao país "PT"
        "data": {
          "type": "countries",                        // [OBRIGATÓRIO]
          "id": "<id do país>"                        // [OBRIGATÓRIO] Vd. NOTA 1
        }
      }
    }
  }
}

NOTA 1: O "id" interno do país deve ser obtido por um GET /countries?filter[iso_alpha_2]=PT|<o código do país>... São também suportados dois "países" adicionais: "PT-AC" (Portugal, Açores) e "PT-MA" (Portugal, Madeira).

E-mail

De modo a associar um email a um cliente, deverá realizar o seguinte pedido

patch

Body

Responses

200

OK

application/json

patch/email_addresses

PATCH /email_addresses HTTP/1.1
Content-Type: application/json
Accept: */*
Content-Length: 636

{
  "data": {
    "type": "email_addresses",
    "attributes": {
      "id": 1,
      "due_days": "text",
      "payment_mechanism": "text",
      "payment_reference": "text",
      "retention_value": "text",
      "sales_price": "text",
      "gobal_settlement_percentage_formula": "text",
      "line_settlement_percentage_formula": "text",
      "retention_type": "text",
      "apply_retention_to": "text",
      "currency_iso_code": "text",
      "bank_account_id": "text",
      "cash_account_id": "text",
      "direct_debit": "text",
      "direct_debit_customer_code": "text",
      "direct_debit_customer_date": "text",
      "direct_debit_customer_account": "text",
      "direct_debit_bank_account_id": "text",
      "direct_debit_document_series_id": "text"
    },
    "relationships": {},
    "id": "text"
  }
}

200

OK

{
  "data": {
    "type": "email_addresses",
    "id": null,
    "attributes": {
      "id": 1,
      "due_days": "text",
      "payment_mechanism": "text",
      "payment_reference": "text",
      "retention_value": "text",
      "sales_price": "text",
      "gobal_settlement_percentage_formula": "text",
      "line_settlement_percentage_formula": "text",
      "retention_type": "text",
      "apply_retention_to": "text",
      "currency_iso_code": "text",
      "bank_account_id": "text",
      "cash_account_id": "text",
      "direct_debit": "text",
      "direct_debit_customer_code": "text",
      "direct_debit_customer_date": "text",
      "direct_debit_customer_account": "text",
      "direct_debit_bank_account_id": "text",
      "direct_debit_document_series_id": "text"
    },
    "relationships": {}
  }
}

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

No pedido acima, o <access_token> corresponde ao token de acesso válido devolvido pelo serviço de OAuth, e o <payload JSON> deverá ter o seguinte formato

{
  "data": {
    "type": "email_addresses",                        // [OBRIGATÓRIO]
    "id": "<id do endereço de email do cliente>",     // [OBRIGATÓRIO]
    "attributes": {
      "email": "[e-mail]",                      // [OBRIGATÓRIO]
    }
  }
}