Trigger Fiscal Sync - payana-docs

Trigger fiscal sync (SAT or DIAN)

curl --request POST \
  --url https://api.prod.payana.cloud/public/api/v1/fiscal-sync \
  --header 'api-key: <api-key>'

const options = {method: 'POST', headers: {'api-key': '<api-key>'}};

fetch('https://api.prod.payana.cloud/public/api/v1/fiscal-sync', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.prod.payana.cloud/public/api/v1/fiscal-sync",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_HTTPHEADER => [
    "api-key: <api-key>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://api.prod.payana.cloud/public/api/v1/fiscal-sync"

	req, _ := http.NewRequest("POST", url, nil)

	req.Header.Add("api-key", "<api-key>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

require 'uri'
require 'net/http'

url = URI("https://api.prod.payana.cloud/public/api/v1/fiscal-sync")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["api-key"] = '<api-key>'

response = http.request(request)
puts response.read_body

{
  "country": "MEX",
  "status": "accepted",
  "started_at": "2026-06-22T15:30:00.000Z",
  "sync_from": "2026-06-21T15:30:00.000-06:00",
  "sync_to": "2026-06-22T15:30:00.000-06:00",
  "extraction_id": "ext-abc123"
}

POST

fiscal-sync

Trigger fiscal sync (SAT or DIAN)

curl --request POST \
  --url https://api.prod.payana.cloud/public/api/v1/fiscal-sync \
  --header 'api-key: <api-key>'

const options = {method: 'POST', headers: {'api-key': '<api-key>'}};

fetch('https://api.prod.payana.cloud/public/api/v1/fiscal-sync', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.prod.payana.cloud/public/api/v1/fiscal-sync",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_HTTPHEADER => [
    "api-key: <api-key>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://api.prod.payana.cloud/public/api/v1/fiscal-sync"

	req, _ := http.NewRequest("POST", url, nil)

	req.Header.Add("api-key", "<api-key>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

require 'uri'
require 'net/http'

url = URI("https://api.prod.payana.cloud/public/api/v1/fiscal-sync")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["api-key"] = '<api-key>'

response = http.request(request)
puts response.read_body

{
  "country": "MEX",
  "status": "accepted",
  "started_at": "2026-06-22T15:30:00.000Z",
  "sync_from": "2026-06-21T15:30:00.000-06:00",
  "sync_to": "2026-06-22T15:30:00.000-06:00",
  "extraction_id": "ext-abc123"
}

Dispara una sincronización fiscal para la compañía asociada a tu API key. Payana resuelve el país automáticamente: México usa extracción SAT (Satws); Colombia inicia el flujo DIAN vía sincronización automática por correo. El endpoint no acepta parámetros en el body. La ventana de fechas se calcula en el servidor según el país y el historial de sincronización de la compañía.

Requisitos previos

México (SAT)

CIEC registrada y válida en Payana para el RFC de la compañía.
La API key debe pertenecer a una compañía de México.

Colombia (DIAN)

Sincronización automática DIAN configurada (reenvío del correo de la DIAN a Payana).
Credenciales DIAN registradas en Payana (NIT empresa y representante legal).

Comportamiento

País	Qué hace el `202 Accepted`	Ventana de sincronización
MEX	Crea una extracción Satws de facturas recibidas	Últimas 24 horas (zona `America/Mexico_City`)
COL	Solicita token de acceso DIAN y deja lista la ventana para el pipeline de correo	Desde `last_sync_at + 1 día` hasta hoy; si nunca hubo sync, 45 días hacia atrás

En Colombia, la respuesta 202 significa que Payana aceptó la solicitud y solicitó el token DIAN. La descarga de facturas ocurre de forma asíncrona cuando el pipeline de correo procesa el enlace de la DIAN. Consulta el progreso con GET /fiscal-sync/status.

Cuando aparezcan documentos nuevos, Payana puede enviar el webhook document.created.

Rate limit

Solo se permite una sincronización fiscal por hora por compañía (independiente del país). Si superas el límite, recibes 429 con el campo retry_after_seconds.

Ejemplo

curl -X POST "https://api.prod.payana.cloud/public/api/v1/fiscal-sync" \
  -H "api-key: YOUR_API_KEY"

Respuesta exitosa — México

{
  "country": "MEX",
  "status": "accepted",
  "started_at": "2026-06-22T15:30:00.000Z",
  "sync_from": "2026-06-21T15:30:00.000-06:00",
  "sync_to": "2026-06-22T15:30:00.000-06:00",
  "extraction_id": "ext-abc123"
}

Respuesta exitosa — Colombia

{
  "country": "COL",
  "status": "accepted",
  "started_at": "2026-06-22T15:30:00.000Z",
  "sync_from": "2026-06-10",
  "sync_to": "2026-06-22"
}

Errores

Código HTTP	Código	Cuándo
`401`	—	Falta el header `api-key` o la clave es inválida.
`403`	`dian_automatic_sync_not_configured`	Colombia: la compañía no tiene reenvío de correo DIAN configurado.
`422`	`sat_credentials_not_configured`	México: no hay CIEC registrada.
`422`	`sat_ciec_pending`	México: la CIEC está en validación.
`422`	`sat_ciec_invalid`	México: la CIEC es inválida o fue rechazada por el SAT.
`422`	`dian_credentials_not_configured`	Colombia: faltan credenciales DIAN.
`422`	`dian_sync_window_empty`	Colombia: no hay documentos nuevos (la última sync es demasiado reciente).
`422`	`fiscal_sync_not_supported_for_country`	El país de la compañía no soporta este endpoint.
`429`	`fiscal_sync_rate_limited`	Ya se disparó una sync en la última hora. Revisa `retry_after_seconds`.

Para consultar el estado después de un 202, usa GET /fiscal-sync/status pasando started_at con el valor de started_at de la respuesta.

Authorizations

api-key

string

header

required

API key provista por Payana.

Response

Solicitud aceptada. La sincronización fue iniciada (MEX) o encolada (COL).

country

enum<string>

required

País de la compañía.

Available options:

MEX,

COL

status

string

required

La solicitud fue aceptada.

Allowed value: "accepted"

started_at

string<date-time>

required

Timestamp de inicio. Úsalo como started_at en GET /fiscal-sync/status.

sync_to

string

required

Fin de la ventana de sincronización.

sync_from

string | null

Inicio de la ventana de sincronización (ISO 8601 en MEX, fecha YYYY-MM-DD en COL).

extraction_id

string

Identificador Satws de la extracción. Solo presente en respuestas de México.

⌘I

​Requisitos previos

​México (SAT)

​Colombia (DIAN)

​Comportamiento

​Rate limit

​Ejemplo

​Respuesta exitosa — México

​Respuesta exitosa — Colombia

​Errores

Authorizations

Response

Requisitos previos

México (SAT)

Colombia (DIAN)

Comportamiento

Rate limit

Ejemplo

Respuesta exitosa — México

Respuesta exitosa — Colombia

Errores