> For the complete documentation index, see [llms.txt](https://ouvretaferme.gitbook.io/ouvretaferme/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://ouvretaferme.gitbook.io/ouvretaferme/endpoints/gestion/declarations-de-tva.md).

# Déclarations de TVA

Les déclarations de TVA de votre structure, avec leur période, le formulaire retenu et son millésime, et les dates auxquelles elles ont été déclarées, comptabilisées et payées. En lecture seule.

## Lister les déclarations de TVA

> Scope requis : \`accounting:read\`.

```json
{"openapi":"3.0.3","info":{"title":"API Ouvretaferme","version":"0.1beta"},"tags":[{"name":"Déclarations de TVA"}],"servers":[{"url":"https://api.ouvretaferme.org/0.1beta"}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","description":"Clé API personnelle ou jeton OAuth2 d'une application tierce, présenté dans l'en-tête `Authorization: Bearer`. Voir la section Authentification."}},"schemas":{"Declaration":{"type":"object","properties":{"id":{"type":"integer","format":"int64","readOnly":true},"financialYear":{"type":"integer","format":"int64","description":"Identifiant d'un élément `FinancialYear`."},"from":{"type":"string","format":"date"},"to":{"type":"string","format":"date"},"limit":{"type":"string","format":"date"},"cerfa":{"type":"string","enum":["ca3","ca12","ca12a"],"description":"Cerfa. Valeurs : `ca12` (CA12), `ca12a` (CA12A), `ca3` (CA3)."},"cerfaYear":{"type":"integer","nullable":true},"status":{"type":"string","enum":["draft","declared","accounted","paid"],"description":"Status. Valeurs : `declared` (Déclarée), `draft` (Créée), `accounted` (Comptabilisée), `paid` (Payée)."},"associates":{"type":"integer","nullable":true},"expertMode":{"type":"boolean"},"data":{"type":"object","description":"Cases du formulaire, indexées par leur identifiant. Les montants sont transmis en chaîne, et quelques cases portent une structure plutôt qu'une valeur."},"declaredAt":{"type":"string","pattern":"^[0-9]{4}-[0-9]{2}-[0-9]{2} [0-9]{2}:[0-9]{2}:[0-9]{2}$","description":"Marquée \"déclarée\" le. Date et heure, au format AAAA-MM-JJ HH:MM:SS.","nullable":true},"accountedAt":{"type":"string","pattern":"^[0-9]{4}-[0-9]{2}-[0-9]{2} [0-9]{2}:[0-9]{2}:[0-9]{2}$","description":"Date et heure, au format AAAA-MM-JJ HH:MM:SS.","nullable":true},"accountedWithOperations":{"type":"boolean","nullable":true},"paidAt":{"type":"string","pattern":"^[0-9]{4}-[0-9]{2}-[0-9]{2} [0-9]{2}:[0-9]{2}:[0-9]{2}$","description":"Date et heure, au format AAAA-MM-JJ HH:MM:SS.","nullable":true}},"title":"Déclarations de TVA","description":"Les déclarations de TVA de votre structure, avec leur période, le formulaire retenu et son millésime, et les dates auxquelles elles ont été déclarées, comptabilisées et payées. En lecture seule."},"Error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","resource_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"}}}},"responses":{"ValidationError":{"description":"Un champ, un filtre ou un argument ne respecte pas les règles de validation, ou le corps n'est pas un objet JSON.","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/Error"}}}}},"AuthenticationError":{"description":"Clé API ou jeton absent, invalide, expiré ou révoqué.","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/Error"}}}}},"Forbidden":{"description":"Le jeton ne porte pas le scope requis, l'écriture n'est pas ouverte à cette structure, la structure n'a pas l'abonnement qui ouvre l'API, ou la personne qui a créé la clé n'administre plus la structure.","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/Error"}}}}},"RateLimited":{"description":"Trop d'appels. L'en-tête `Retry-After` donne le nombre de secondes à attendre.","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/Error"}}}},"headers":{"Retry-After":{"description":"Nombre de secondes à attendre avant le prochain appel.","schema":{"type":"integer"}}}}}},"paths":{"/vatDeclarationList":{"get":{"operationId":"getVatDeclarationList","tags":["Déclarations de TVA"],"summary":"Lister les déclarations de TVA","description":"Scope requis : `accounting:read`.","parameters":[{"name":"start","in":"query","required":false,"description":"Rang du premier élément rendu, à partir de 1.","schema":{"type":"integer","minimum":1,"default":1}},{"name":"limit","in":"query","required":false,"description":"Nombre d'éléments rendus, 100 par défaut et 500 au plus. À 0, seul le total est rendu.","schema":{"type":"integer","minimum":0,"maximum":500,"default":100}},{"name":"ids","in":"query","required":false,"description":"Ne rend que ces identifiants, 100 au plus, séparés par des virgules.","style":"form","explode":false,"schema":{"type":"array","items":{"type":"integer","format":"int64"},"maxItems":100}},{"name":"afterId","in":"query","required":false,"description":"Ne rend que les éléments d'identifiant supérieur, pour parcourir une liste sans décalage quand elle change pendant la lecture.","schema":{"type":"integer","format":"int64"}},{"name":"beforeId","in":"query","required":false,"description":"Ne rend que les éléments d'identifiant inférieur.","schema":{"type":"integer","format":"int64"}},{"name":"financialYear","in":"query","required":false,"description":"Identifiant d'un élément `FinancialYear`.","schema":{"type":"integer","format":"int64"}},{"name":"status","in":"query","required":false,"description":"Status. Valeurs : `declared` (Déclarée), `draft` (Créée), `accounted` (Comptabilisée), `paid` (Payée).","schema":{"type":"string","enum":["draft","declared","accounted","paid"]}}],"responses":{"200":{"description":"Liste paginée des déclarations de TVA.","content":{"application/json":{"schema":{"type":"object","properties":{"count":{"type":"integer","description":"Nombre d'éléments que retiennent les filtres, sans tenir compte de la pagination (`start`, `limit`, `afterId`, `beforeId`)."},"list":{"type":"array","items":{"$ref":"#/components/schemas/Declaration"}}}}}}},"400":{"$ref":"#/components/responses/ValidationError"},"401":{"$ref":"#/components/responses/AuthenticationError"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"}}}}}}
```

## Consulter une déclaration de TVA

> Scope requis : \`accounting:read\`. Pour lire plusieurs déclarations de TVA, \`GET /vatDeclarationList?ids=12,15,18\` en rend jusqu'à 100, et ne compte que pour un appel.

```json
{"openapi":"3.0.3","info":{"title":"API Ouvretaferme","version":"0.1beta"},"tags":[{"name":"Déclarations de TVA"}],"servers":[{"url":"https://api.ouvretaferme.org/0.1beta"}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","description":"Clé API personnelle ou jeton OAuth2 d'une application tierce, présenté dans l'en-tête `Authorization: Bearer`. Voir la section Authentification."}},"schemas":{"Declaration":{"type":"object","properties":{"id":{"type":"integer","format":"int64","readOnly":true},"financialYear":{"type":"integer","format":"int64","description":"Identifiant d'un élément `FinancialYear`."},"from":{"type":"string","format":"date"},"to":{"type":"string","format":"date"},"limit":{"type":"string","format":"date"},"cerfa":{"type":"string","enum":["ca3","ca12","ca12a"],"description":"Cerfa. Valeurs : `ca12` (CA12), `ca12a` (CA12A), `ca3` (CA3)."},"cerfaYear":{"type":"integer","nullable":true},"status":{"type":"string","enum":["draft","declared","accounted","paid"],"description":"Status. Valeurs : `declared` (Déclarée), `draft` (Créée), `accounted` (Comptabilisée), `paid` (Payée)."},"associates":{"type":"integer","nullable":true},"expertMode":{"type":"boolean"},"data":{"type":"object","description":"Cases du formulaire, indexées par leur identifiant. Les montants sont transmis en chaîne, et quelques cases portent une structure plutôt qu'une valeur."},"declaredAt":{"type":"string","pattern":"^[0-9]{4}-[0-9]{2}-[0-9]{2} [0-9]{2}:[0-9]{2}:[0-9]{2}$","description":"Marquée \"déclarée\" le. Date et heure, au format AAAA-MM-JJ HH:MM:SS.","nullable":true},"accountedAt":{"type":"string","pattern":"^[0-9]{4}-[0-9]{2}-[0-9]{2} [0-9]{2}:[0-9]{2}:[0-9]{2}$","description":"Date et heure, au format AAAA-MM-JJ HH:MM:SS.","nullable":true},"accountedWithOperations":{"type":"boolean","nullable":true},"paidAt":{"type":"string","pattern":"^[0-9]{4}-[0-9]{2}-[0-9]{2} [0-9]{2}:[0-9]{2}:[0-9]{2}$","description":"Date et heure, au format AAAA-MM-JJ HH:MM:SS.","nullable":true}},"title":"Déclarations de TVA","description":"Les déclarations de TVA de votre structure, avec leur période, le formulaire retenu et son millésime, et les dates auxquelles elles ont été déclarées, comptabilisées et payées. En lecture seule."},"Error":{"type":"object","properties":{"type":{"type":"string","enum":["authentication_error","resource_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"}}}},"responses":{"ValidationError":{"description":"Un champ, un filtre ou un argument ne respecte pas les règles de validation, ou le corps n'est pas un objet JSON.","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/Error"}}}}},"AuthenticationError":{"description":"Clé API ou jeton absent, invalide, expiré ou révoqué.","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/Error"}}}}},"Forbidden":{"description":"Le jeton ne porte pas le scope requis, l'écriture n'est pas ouverte à cette structure, la structure n'a pas l'abonnement qui ouvre l'API, ou la personne qui a créé la clé n'administre plus la structure.","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/Error"}}}}},"NotFound":{"description":"Aucun élément avec cet identifiant pour votre structure.","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/Error"}}}}},"RateLimited":{"description":"Trop d'appels. L'en-tête `Retry-After` donne le nombre de secondes à attendre.","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/Error"}}}},"headers":{"Retry-After":{"description":"Nombre de secondes à attendre avant le prochain appel.","schema":{"type":"integer"}}}}}},"paths":{"/vatDeclaration/{id}":{"get":{"operationId":"getVatDeclarationById","tags":["Déclarations de TVA"],"summary":"Consulter une déclaration de TVA","description":"Scope requis : `accounting:read`. Pour lire plusieurs déclarations de TVA, `GET /vatDeclarationList?ids=12,15,18` en rend jusqu'à 100, et ne compte que pour un appel.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"integer","format":"int64"}}],"responses":{"200":{"description":"Déclaration de TVA demandée.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Declaration"}}}},"400":{"$ref":"#/components/responses/ValidationError"},"401":{"$ref":"#/components/responses/AuthenticationError"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimited"}}}}}}
```