Guida ai casi d'uso dell'API delle fatture v2024-06-19
Scopri come utilizzare l'API delle fatture.
Versione API: 2024-06-19
Cos'è l'API delle fatture?
Puoi usare API dei partner di vendita per le fatture per recuperare e gestire una serie di operazioni relative alle fatture che possono aiutare i partner di vendita a gestire la loro contabilità.
Importante
Questa API è in grado di recuperare solo Fatture FBA brasiliane. Non puoi utilizzare questa API per nessun altro tipo di fattura.
Caratteristiche principali
- Cerca le fatture in base ai loro attributi
- Esporta e scarica le fatture
Terminologia
- Sefaz: Amministrazione fiscale statale brasiliana (Secretaria da Fazenda).
Tutorial: Esportazione dei file delle fatture
Scopri come esportare e scaricare i file delle fatture.
Prerequisiti
Per completare questo tutorial, devi avere:
- Autorizzazione del partner di vendita per il quale stai effettuando chiamate. Per ulteriori informazioni, consulta Autorizzazione delle applicazioni Selling Partner API.
- Il ruolo di fatturazione fiscale assegnato al tuo profilo di sviluppatore.
- Il ruolo di fatturazione fiscale selezionato nella pagina di registrazione dell'app per la tua applicazione.
Fase 1. Crea un'esportazione di fatture
Chiama il createInvoicesExport
operazione e specifica il marketplace, l'intervallo di date e tutti i parametri opzionali che desideri includere.
Se la richiesta va a buon fine, la risposta include exportId
valore.
Parametri del corpo
Nome | Descrizione | Obbligatorio |
---|---|---|
marketplaceId | Le fatture restituite corrispondono al marketplace specificato. Tipo: stringa | Sì |
dateStart | La prima data di creazione della fattura per le fatture che desideri includere nella risposta. Le date sono scadute ISO 8601 formato. Tipo: stringa (data) | No |
dateEnd | L'ultima data di creazione della fattura per le fatture che desideri includere nella risposta. Le date sono scadute ISO 8601 formato. Tipo: stringa (data) | No |
Suggerimento
Per ridurre i tempi di elaborazione delle esportazioni, utilizzate intervalli di date brevi per
dateStart
edateEnd
. L'intervallo ottimale è di un giorno.
Esempio di richiesta
POST https://sellingpartnerapi-na.amazon.com/invoices/v1/exports?marketplaceId=A2Q3Y263D00KWC&dateStart=2024-07-09T00:00:00Z&dateEnd=2024-07-10T00:00:00Z
Risposta
Nome | Descrizione |
---|---|
exportId | L'identificatore di esportazione. Tipo: stringa |
Esempio di risposta
{
"exportId": "4bdd8293-0cd7-4208-bed5-78b2c6ecefef"
}
Fase 2 Verificare che l'elaborazione dell'esportazione sia completa
Chiama periodicamente il getInvoicesExport
operazione: superamento del exportId
valore che hai ricevuto in Fase 1--fino al completamento dell'elaborazione (processingStatus
è CANCELLED
, DONE
, oppure FATAL
). A questo punto, la risposta include un exportDocumentId
valore se i dati della fattura sono disponibili.
Parametri del percorso
Nome | Descrizione | Obbligatorio |
---|---|---|
exportId | L'identificatore per l'esportazione. Tipo: stringa | Sì |
Esempio di richiesta
GET https://sellingpartnerapi-na.amazon.com/invoices/v1/exports/4bdd8293-0cd7-4208-bed5-78b2c6ecefef
Risposta
Nome | Descrizione |
---|---|
errorMessage | Quando la generazione dell'esportazione fallisce, questo attributo contiene una descrizione dell'errore. Tipo: stringa |
exportDocumentIds | Un elenco con gli identificatori di ogni documento di esportazione. Tipo: array |
exportId | L'identificatore di esportazione. Tipo: stringa |
generateExportFinished | La data e l'ora in cui è terminata la generazione dell'esportazione, nel formato data-ora ISO 8601. Tipo: stringa |
generateExportStarted | La data e l'ora di inizio della generazione dell'esportazione, nel formato data-ora ISO 8601. Tipo: stringa |
status | Lo stato dell'elaborazione. Tipo: enum ( REQUESTED , PROCESSING , DONE , ERROR ) |
Esempio di risposta
{
"export": {
"errorMessage": "",
"exportDocumentIds": [
"18c598f5-75db-4c1a-bd3e-4c64b36781c5"
],
"exportId": "4bdd8293-0cd7-4208-bed5-78b2c6ecefef",
"generateExportFinished": "2024-07-10T16:00:00.000Z",
"generateExportStarted": "2024-07-10T15:00:00.000Z",
"status": "DONE"
}
}
Fase 3. Ottieni l'URL del documento di fatturazione
Chiama il getInvoicesDocument
operazione, superando il exportDocumentId
valore da Fase 2.
La risposta contiene un URL prefirmato che puoi utilizzare per accedere all'esportazione della fattura. Se i contenuti sono compressi, viene fornito l'algoritmo di compressione. L'URL scade dopo 30 secondi.
Parametri del percorso
Nome | Descrizione | Obbligatorio |
---|---|---|
invoicesDocumentId | L'identificatore del documento di esportazione. Tipo: stringa | Sì |
Esempio di richiesta
GET https://sellingpartnerapi-na.amazon.com/invoices/v1/documents/18c598f5-75db-4c1a-bd3e-4c64b36781c5
Risposta
Nome | Descrizione |
---|---|
invoicesDocumentId | L'identificatore del documento di esportazione. Tipo: stringa |
invoicesDocumentUrl | Un URL prefirmato che puoi utilizzare per scaricare le fatture (in formato ZIP). Tipo: stringa |
Esempio di risposta
{
"exportDocumentId": "18c598f5-75db-4c1a-bd3e-4c64b36781c5",
"url": "https://d34o8swod1owfl.cloudfront.net/SampleResult%2BKey%3DSample%2BINITVEC%3D58+fa+bf+a7+08+11+95+0f+c1+a8+c6+e0+d5+6f+ae+c8"
}
Updated 5 months ago