> ## Documentation Index
> Fetch the complete documentation index at: https://docs.gigstack.io/llms.txt
> Use this file to discover all available pages before exploring further.

# SAT Lists API Guide

> Integration guide for SAT Lists

## Overview

The SAT publishes lists of taxpayers under **Artículo 69**, **Artículo 69-B** and **Artículo 69-B Bis** of the Código Fiscal — for example taxpayers with cancelled certificates, taxpayers that could not be located, and companies presumed or confirmed to issue simulated invoices (EFOS). Invoicing a taxpayer on one of the risky lists can cost you the deduction.

gigstack mirrors these lists and re-syncs them from the SAT's published CSVs **every Sunday**, so you can screen a counterparty's RFC with one call. It also consults the SAT's public *Opinión del Cumplimiento* (32-D) service.

Base path: `https://api.gigstack.io/v2/sat-lists`. All endpoints are read-only and require a valid API key.

## Endpoints

### List the Tracked Lists

```http theme={null}
GET /sat-lists
```

Returns every list gigstack tracks and the result of its latest sync.

| Field | Description |
| - | - |
| `key` | Stable list identifier |
| `label` | Name as published by the SAT |
| `source` | `art_69`, `art_69b` or `art_69b_bis` |
| `is_risky` | `true` for lists that indicate a counterparty you should not invoice (e.g. `Cancelados`, `Definitivos 69-B`, `No localizados`, `CSD sin efectos`); `false` for informational lists |
| `filename` | Source CSV published by the SAT |
| `sync` | Latest sync: `last_sync_at`, `last_status` (`ok` \| `error`), `row_count`, `previous_row_count`, … `null` if the list has never synced |

```bash theme={null}
curl https://api.gigstack.io/v2/sat-lists \
  -H "Authorization: Bearer YOUR_TOKEN"
```

### Check an RFC

```http theme={null}
GET /sat-lists/check/{rfc}
```

| Parameter | In | Description |
| - | - | - |
| `rfc` | path | RFC to check, 10-13 characters, case-insensitive |
| `risky_only` | query | `true` to return only entries from lists flagged as risky |

```bash theme={null}
curl "https://api.gigstack.io/v2/sat-lists/check/XAXX010101000" \
  -H "Authorization: Bearer YOUR_TOKEN"
```

The response `data`:

| Field | Description |
| - | - |
| `rfc` | The RFC checked, uppercased |
| `found` | `true` if the RFC appears on at least one list |
| `is_risky` | `true` if it appears on at least one risky list |
| `risky_lists` | Keys of the risky lists it appears on |
| `entries` | Every matching entry: `list_key`, `list_label`, `source`, `is_risky`, `detail` (extra CSV columns, when published), `last_seen_at` |

An RFC on no list returns `200` with `found: false` — a clean RFC is not a `404`. An RFC that is not 10-13 characters returns `400`.

**Typical use:** before issuing an invoice or registering a new supplier, call this endpoint and block or flag the operation when `is_risky` is `true`.

### Opinión del Cumplimiento (32-D)

```http theme={null}
GET /sat-lists/32d/{rfc}
```

Consults the SAT's public *Opinión del Cumplimiento de Obligaciones Fiscales* service for an RFC.

**Read this before building on it.** The SAT's public service only publishes **positive** opinions, and only for taxpayers who authorized public disclosure. There are exactly two outcomes:

| `status` | `found` | Meaning |
| - | - | - |
| `positiva` | `true` | The SAT publishes a positive opinion. `pdf_url` links to the stored constancia PDF |
| `no_autorizado` | `false` | The SAT publishes nothing for this RFC. **The result is unknown** — it is *not* a negative opinion |

Never present `no_autorizado` to a user as "opinión negativa", "incumplido" or anything equivalent: this service cannot tell you that a taxpayer is non-compliant. The response also includes `checked_at` (epoch ms) and, for `no_autorizado`, the SAT's own `message`.

If the SAT cannot be reached or its page cannot be parsed, the call returns `500`. That is never reported as `no_autorizado`, so a `no_autorizado` is always a real answer from the SAT.

```bash theme={null}
curl https://api.gigstack.io/v2/sat-lists/32d/EKU9003173C9 \
  -H "Authorization: Bearer YOUR_TOKEN"
```

## Errors

| Status | When |
| - | - |
| `400` | RFC is not 10-13 characters |
| `500` | Unexpected failure, or the SAT could not be reached (32-D) |

## Related Resources

* [Clients API](/guides/clients) - EFOS checks run when you validate a client
* [Tax Regimes Catalog](/guides/catalogs/tax_regimes)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.