# Consultar las declaraciones de un emisor en el SAT

`POST https://api.fiscalisto.com/v1/sat_declarations/refresh`

Entra al SAT con la e.firma guardada del emisor y trae las declaraciones que presentó: provisionales o definitivas (desde 2022), la anual de persona moral (desde 2019) y las del servicio anterior Declaraciones y pagos, con su PDF, su acuse y sus cifras. La primera consulta trae todos los años que el SAT conserva; las siguientes, este año y el anterior. Solo consulta: nunca presenta ni firma nada. En producción usa 1 timbre por consulta (regresa si el SAT no contesta) y se puede hacer una vez cada 10 minutos por emisor. Contesta en menos de un minuto; si queda algo por bajar (status processing), sigue solo en la siguiente hora sin otro timbre. En pruebas no se le pregunta al SAT: trae declaraciones de ejemplo al instante.

## Parámetros

| Nombre | Dónde | Obligatorio | Descripción |
| --- | --- | --- | --- |
| `Idempotency-Key` | encabezado |  | Opcional (los SDK la mandan solos). Si la respuesta se pierde, repita la solicitud con el mismo valor durante 24 horas: contesta lo mismo, con idempotent-replayed: true, y no lo hace dos veces (ni crea, ni manda correos, ni cobra). |

## Cuerpo

| Campo | Tipo | Obligatorio | Descripción |
| --- | --- | --- | --- |
| `issuer` | string |  | El emisor (iss_…). Por omisión, su único emisor. |

Ejemplo:

```json
{}
```

## Con el SDK de TypeScript

```ts
import { Fiscalisto } from "fiscalisto";

// La llave viene de FISCALISTO_API_KEY.
const fiscalisto = new Fiscalisto();

const satDeclarationsRefresh = await fiscalisto.satDeclarations.refresh({ idempotencyKey: "pedido-A-1042" });
```

## Con el SDK de Python

```python
from fiscalisto import Fiscalisto

# La llave viene de FISCALISTO_API_KEY.
fiscalisto = Fiscalisto()

sat_declarations_refresh = fiscalisto.sat_declarations.refresh(idempotency_key="pedido-A-1042")
```

## Con el SDK de PHP

```php
<?php

use Fiscalisto\Fiscalisto;

// La llave viene de FISCALISTO_API_KEY.
$fiscalisto = new Fiscalisto();

$satDeclarationsRefresh = $fiscalisto->satDeclarations->refresh([], ['idempotency_key' => 'pedido-A-1042']);
```

## Con el SDK de .NET

```csharp
using Fiscalisto;

// La llave viene de FISCALISTO_API_KEY.
var fiscalisto = new FiscalistoClient();

var satDeclarationsRefresh = await fiscalisto.SatDeclarations.RefreshAsync(options: new RequestOptions { IdempotencyKey = "pedido-A-1042" });
```

## Con el SDK de Go

```go
package main

import (
	"context"
	"fmt"
	"log"

	fiscalisto "fiscalisto.com/go"
)

func main() {
	// La llave viene de FISCALISTO_API_KEY.
	client, err := fiscalisto.NewClient("")
	if err != nil {
		log.Fatal(err)
	}
	ctx := context.Background()

	satDeclarationsRefresh, err := client.SatDeclarations.Refresh(ctx, nil, fiscalisto.WithIdempotencyKey("pedido-A-1042"))
	if err != nil {
		log.Fatal(err)
	}
	fmt.Printf("%+v\n", *satDeclarationsRefresh)
}
```

## Con el SDK de Java

```java
import com.fiscalisto.FiscalistoClient;
import com.fiscalisto.RequestOptions;

// La llave viene de FISCALISTO_API_KEY.
var fiscalisto = new FiscalistoClient();

var satDeclarationsRefresh = fiscalisto.satDeclarations().refresh(null, RequestOptions.idempotencyKey("pedido-A-1042"));
System.out.println(satDeclarationsRefresh);
```

## Respuesta 200

Correcto.

Un objeto `SatDeclarationsRefresh`:

| Campo | Tipo | Siempre viene | Descripción |
| --- | --- | --- | --- |
| `object` | `"sat_declarations_refresh"` | sí | Qué tipo de objeto es («invoice», «customer»…). |
| `livemode` | boolean | sí | true en producción (llaves fk_live_), false en pruebas (fk_test_). Lo de pruebas no vale ante el SAT. |
| `issuer` | string | sí | El emisor consultado. |
| `status` | `completed`, `processing` | sí | completed (ya bajó todo) o processing (queda algo por bajar: sigue solo en la siguiente hora, sin otro timbre). |
| `found` | integer | sí | Cuántas declaraciones listó el SAT en los años consultados. (de -9007199254740991 a 9007199254740991) |
| `downloaded` | integer | sí | Cuántos archivos bajó en esta consulta. (de -9007199254740991 a 9007199254740991) |
| `pending` | integer | sí | Cuántas declaraciones quedan con archivos por bajar. (de -9007199254740991 a 9007199254740991) |
| `warning` | string o null | sí | Si una parte del SAT falló (por ejemplo, la anual), lo que dijo; lo demás sí se trajo. null si todo salió. |
| `refreshed_at` | string (date-time) | sí | Cuándo se consultó. |
| `next_refresh_at` | string (date-time) | sí | Desde cuándo se puede volver a consultar este emisor (10 minutos después). |

```json
{
  "object": "sat_declarations_refresh",
  "livemode": false,
  "issuer": "iss_OufpKqnrvx9p",
  "status": "completed",
  "found": 10,
  "downloaded": 10,
  "pending": 0,
  "warning": null,
  "refreshed_at": "2026-10-26T09:12:00-06:00",
  "next_refresh_at": "2026-10-26T09:22:00-06:00"
}
```

## Errores

Puede responder 400, 401, 403, 404, 429, 500 con el cuerpo de error de siempre; cada código está en https://fiscalisto.com/docs/api/errores.md.