API Versioning Guide

Guidance on changes between versions.

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

Invoice

Affected Endpoints: GET /invoices/{id} andGET /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} andGET /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 andGET /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 andGET /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}'