API Versioning Guide

Guidance on changes between versions.

Version: 2020-01-01 to 2020-06-28

Invoice

Affected Endpoints: GET /invoices/{id} and GET /taxpayers/{taxpayerID}/invoices

  • The amount property has been removed from API responses. Use the total property instead.

  • Retrieval by invoice's uuid at /invoices/{id} is now removed. To retrieve an invoice, use the invoice's id at the specified endpoint. To find an invoice using its uuid, filter the invoice collection at /taxpayer/{taxpayerId}/invoices?uuid[]={uuid}.

  • Previously, the @iri property for an invoice pointed to the resource using uuid, like /invoices/{uuid}. Now, it points using its id, like /invoices/{id}.

Link

Affected Endpoint: GET /links

  • Filtering links by status is removed. Use credential.status instead. For example, utilize GET /links?credential.status[]=active instead of GET /links?status[]=active.

Tax Return

Affected Endpoints: GET /tax-returns/{id} and GET /taxpayer/{taxpayerID}/tax-returns

  • Retrieval by tax return's operationNumber at /tax-returns/{id} is removed. To retrieve a tax return, use the tax return's id at the mentioned endpoint. To find a tax return using its operationNumber, filter the collection at /taxpayer/{taxpayerId}/tax-returns?operationNumber[]={operationNumber}.

  • Previously, the @iri property for a tax return pointed to the resource using operationNumber, like /tax-returns/{operationNumber}. Now, it directs to its id, like /tax-returns/{id}.

Event

Affected Endpoints: GET /events and GET /events/{id}

  • For events associated to an tax-return, the @iri property now directs to /tax-returns/{id} instead of the previous /tax-returns/{operationNumber}.

  • For events associated to an invoice, the @iri property now directs to /invoices/{id} instead of the previous /invoices/{uuid}.

Extraction

Affected Endpoints: GET /extractions and GET /extractions/{id}

  • The periodFrom property has been removed. Use options.period.from instead.

  • The periodTo property has been removed. Use options.period.to instead.

File

Affected Endpoint: GET /file/{id}

  • For files associated to an tax-return, the @iri property now directs to /tax-returns/{id}, instead of the previous /tax-returns/{operationNumber}.

  • For files associated to an invoice, the @iri property now directs to /invoices/{id}, instead of the previous /invoices/{uuid}.

Trying Out This Version

If you want to test this version, you can do so by making any request with the Accept-Version header pointing to the latest version:

  curl -i 'https://api.syntage.com/taxpayers/{taxpayerId}/invoices' \
    --header 'Accept-Version: 2020-06-28' \
    --header 'X-Api-Key: {apiKey}'